@tekmidian/pai 0.5.6 → 0.5.7

package/templates/skills/CORE/HookSystem.md

@@ -0,0 +1,1082 @@
+# Hook System
+
+**Event-Driven Automation Infrastructure**
+
+**Location:** `${PAI_DIR}/Hooks/`
+**Configuration:** `${PAI_DIR}/settings.json`
+**Status:** Active - All hooks running in production
+
+---
+
+## Overview
+
+The PAI hook system is an event-driven automation infrastructure built on Claude Code's native hook support. Hooks are executable scripts (TypeScript/Python) that run automatically in response to specific events during Claude Code sessions.
+
+**Core Capabilities:**
+- **Session Management** - Auto-load context, capture summaries, manage state
+- **Voice Notifications** - Text-to-speech announcements for task completions
+- **History Capture** - Automatic work/learning documentation to `${PAI_DIR}/History/`
+- **Multi-Agent Support** - Agent-specific hooks with voice routing
+- **Observability** - Real-time event streaming to dashboard
+- **Tab Titles** - Dynamic terminal tab updates with task context
+
+**Key Principle:** Hooks run asynchronously and fail gracefully. They enhance the user experience but never block Claude Code's core functionality.
+
+---
+
+## Available Hook Types
+
+Claude Code supports the following hook events (from `${PAI_DIR}/Hooks/lib/observability.ts`):
+
+### 1. **SessionStart**
+**When:** Claude Code session begins (new conversation)
+**Use Cases:**
+- Load PAI context from `skills/CORE/SKILL.md`
+- Initialize session state
+- Capture session metadata
+
+**Current Hooks:**
+```typescript
+{
+  "SessionStart": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/load-core-context.ts"
+        },
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/initialize-pai-session.ts"
+        },
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-all-events.ts --event-type SessionStart"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**What They Do:**
+- `load-core-context.ts` - Reads `skills/CORE/SKILL.md` and injects PAI context as `<system-reminder>` at session start
+- `initialize-pai-session.ts` - Sets up session state and environment
+- `capture-all-events.ts` - Logs event to `${PAI_DIR}/History/raw-outputs/YYYY-MM/YYYY-MM-DD_all-events.jsonl`
+
+---
+
+### 2. **SessionEnd**
+**When:** Claude Code session terminates (conversation ends)
+**Use Cases:**
+- Generate session summaries
+- Save session metadata
+- Cleanup temporary state
+
+**Current Hooks:**
+```typescript
+{
+  "SessionEnd": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-session-summary.ts"
+        },
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-all-events.ts --event-type SessionEnd"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**What They Do:**
+- `capture-session-summary.ts` - Analyzes session activity and creates summary document in `${PAI_DIR}/History/sessions/YYYY-MM/`
+- Captures: files changed, commands executed, tools used, session focus, duration
+
+---
+
+### 3. **UserPromptSubmit**
+**When:** User submits a new prompt to Claude
+**Use Cases:**
+- Update UI indicators
+- Pre-process user input
+- Capture prompts for analysis
+
+**Current Hooks:**
+```typescript
+{
+  "UserPromptSubmit": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/update-tab-titles.ts"
+        },
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-all-events.ts --event-type UserPromptSubmit"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**What They Do:**
+- `update-tab-titles.ts` - Updates Kitty terminal tab title with task summary
+- Launches background Haiku summarization for better tab titles
+- Sets `♻️` emoji prefix to indicate processing
+
+---
+
+### 4. **Stop**
+**When:** Main agent (Kai) completes a response
+**Use Cases:**
+- Voice notifications for task completion
+- Capture work summaries and learnings
+- Update terminal tab with completion status
+
+**Current Hooks:**
+```typescript
+{
+  "Stop": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/stop-hook.ts"
+        },
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-all-events.ts --event-type Stop"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**What They Do:**
+- `stop-hook.ts` - THE CRITICAL HOOK for main agent completions
+  - Extracts `🎯 COMPLETED:` line from response
+  - Sends to voice server with PAI's voice ID (`s3TPKV1kjDlVtZbl4Ksh`)
+  - Captures work summaries to `${PAI_DIR}/History/sessions/YYYY-MM/` or learnings to `${PAI_DIR}/History/learnings/YYYY-MM/`
+  - Updates Kitty tab with `✅` prefix
+  - Sends event to observability dashboard
+
+**Learning Detection:** Automatically identifies learning moments (2+ indicators: problem/issue/bug, fixed/solved, troubleshoot/debug, lesson/takeaway)
+
+---
+
+### 5. **SubagentStop**
+**When:** Subagent (Task tool) completes execution
+**Use Cases:**
+- Agent-specific voice notifications
+- Capture agent outputs
+- Track multi-agent workflows
+
+**Current Hooks:**
+```typescript
+{
+  "SubagentStop": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/subagent-stop-hook.ts"
+        },
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-all-events.ts --event-type SubagentStop"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**What They Do:**
+- `subagent-stop-hook.ts` - Agent-specific completion handling
+  - Waits for Task tool result in transcript
+  - Extracts `[AGENT:type]` tag and completion message
+  - Routes to agent-specific voice (via agent's own voice notification in response)
+  - Captures agent output to appropriate history category
+  - Sends to observability dashboard
+
+**Agent-Specific Routing:**
+- `[AGENT:engineer]` → Engineer voice ID
+- `[AGENT:researcher]` → Researcher voice ID
+- `[AGENT:pentester]` → Pentester voice ID
+- etc.
+
+---
+
+### 6. **PreToolUse**
+**When:** Before Claude executes any tool
+**Use Cases:**
+- Tool usage analytics
+- Pre-execution validation
+- Performance monitoring
+
+**Current Hooks:**
+```typescript
+{
+  "PreToolUse": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-all-events.ts --event-type PreToolUse"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**What They Do:**
+- Captures tool name, input parameters, timestamp
+- Logs to daily events file for analysis
+
+---
+
+### 7. **PostToolUse**
+**When:** After Claude executes any tool
+**Use Cases:**
+- Capture tool outputs
+- Error tracking
+- Performance metrics
+
+**Current Hooks:**
+```typescript
+{
+  "PostToolUse": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-all-events.ts --event-type PostToolUse"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**What They Do:**
+- Captures tool output, execution time, success/failure
+- Logs to `${PAI_DIR}/History/raw-outputs/YYYY-MM/YYYY-MM-DD_all-events.jsonl`
+- Powers observability dashboard
+
+---
+
+### 8. **PreCompact**
+**When:** Before Claude compacts context (long conversations)
+**Use Cases:**
+- Preserve important context
+- Log compaction events
+- Pre-compaction cleanup
+
+**Current Hooks:**
+```typescript
+{
+  "PreCompact": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/context-compression-hook.ts"
+        },
+        {
+          "type": "command",
+          "command": "${PAI_DIR}/Hooks/capture-all-events.ts --event-type PreCompact"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**What They Do:**
+- `context-compression-hook.ts` - Handles context preservation before compaction
+- Captures metadata about compaction events
+
+---
+
+## Configuration
+
+### Location
+**File:** `${PAI_DIR}/settings.json`
+**Section:** `"hooks": { ... }`
+
+### Environment Variables
+Hooks have access to all environment variables from `${PAI_DIR}/settings.json` `"env"` section:
+
+```json
+{
+  "env": {
+    "PAI_DIR": "${HOME}/.claude",
+    "DA": "Kai",
+    "MCP_API_KEY": "...",
+    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000"
+  }
+}
+```
+
+**Key Variables:**
+- `PAI_DIR` - PAI installation directory (always `${HOME}/.claude` or `~/.claude`)
+- `DA` - Digital Assistant name ("Kai")
+- Hook scripts reference `${PAI_DIR}` in command paths
+
+### Hook Configuration Structure
+
+```json
+{
+  "hooks": {
+    "HookEventName": [
+      {
+        "matcher": "pattern",  // Optional: filter which tools/events trigger hook
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PAI_DIR}/Hooks/my-hook.ts --arg value"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Fields:**
+- `HookEventName` - One of: SessionStart, SessionEnd, UserPromptSubmit, Stop, SubagentStop, PreToolUse, PostToolUse, PreCompact
+- `matcher` - Pattern to match (use `"*"` for all tools, or specific tool names)
+- `type` - Always `"command"` (executes external script)
+- `command` - Path to executable hook script (TypeScript/Python/Bash)
+
+### Hook Input (stdin)
+All hooks receive JSON data on stdin:
+
+```typescript
+{
+  session_id: string;         // Unique session identifier
+  transcript_path: string;    // Path to JSONL transcript
+  hook_event_name: string;    // Event that triggered hook
+  prompt?: string;            // User prompt (UserPromptSubmit only)
+  tool_name?: string;         // Tool name (PreToolUse/PostToolUse)
+  tool_input?: any;           // Tool parameters (PreToolUse)
+  tool_output?: any;          // Tool result (PostToolUse)
+  // ... event-specific fields
+}
+```
+
+---
+
+## Common Patterns
+
+### 1. Voice Notifications
+
+**Pattern:** Extract completion message → Send to voice server
+
+```typescript
+// stop-hook.ts pattern
+const completionMessage = extractKaiCompletion(lastMessage);
+
+const payload = {
+  title: 'PAI',
+  message: completionMessage,
+  voice_enabled: true,
+  voice_id: 's3TPKV1kjDlVtZbl4Ksh'  // PAI's ElevenLabs voice
+};
+
+await fetch('http://localhost:8888/notify', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload)
+});
+```
+
+**Agent-Specific Voices:**
+- Main agent (PAI): `s3TPKV1kjDlVtZbl4Ksh`
+- Engineer: `fATgBRI8wg5KkDFg8vBd`
+- Researcher: `AXdMgz6evoL7OPd7eU12`
+- Pentester: `xvHLFjaUEpx4BOf7EiDd`
+- Intern: `d3MFdIuCfbAIwiu7jC4a`
+
+See `skills/CORE/SKILL.md` for complete voice ID mapping.
+
+---
+
+### 2. History Capture (UOCS Pattern)
+
+**Pattern:** Parse structured response → Save to appropriate history directory
+
+**File Naming Convention:**
+```
+YYYY-MM-DD-HHMMSS_TYPE_description.md
+```
+
+**Types:**
+- `WORK` - General task completions
+- `LEARNING` - Problem-solving learnings
+- `SESSION` - Session summaries
+- `RESEARCH` - Research findings (from agents)
+- `FEATURE` - Feature implementations (from agents)
+- `DECISION` - Architectural decisions (from agents)
+
+**Example from stop-hook.ts:**
+```typescript
+const structured = extractStructuredSections(lastMessage);
+const isLearning = isLearningCapture(text, structured);
+const captureType = isLearning ? 'LEARNING' : 'WORK';
+
+const targetDir = isLearning
+  ? join(baseDir, 'history', 'learnings', yearMonth)
+  : join(baseDir, 'history', 'sessions', yearMonth);
+
+const filename = generateFilename(description, captureType);
+writeFileSync(join(targetDir, filename), content);
+```
+
+**Structured Sections Parsed:**
+- `📋 SUMMARY:` - Brief overview
+- `🔍 ANALYSIS:` - Key findings
+- `⚡ ACTIONS:` - Steps taken
+- `✅ RESULTS:` - Outcomes
+- `📊 STATUS:` - Current state
+- `➡️ NEXT:` - Follow-up actions
+- `🎯 COMPLETED:` - **Voice notification line**
+
+---
+
+### 3. Agent Type Detection
+
+**Pattern:** Identify which agent is executing → Route appropriately
+
+```typescript
+// From capture-all-events.ts
+let agentName = getAgentForSession(sessionId);
+
+// Detect from Task tool
+if (hookData.tool_name === 'Task' && hookData.tool_input?.subagent_type) {
+  agentName = hookData.tool_input.subagent_type;
+  setAgentForSession(sessionId, agentName);
+}
+
+// Detect from CLAUDE_CODE_AGENT env variable
+else if (process.env.CLAUDE_CODE_AGENT) {
+  agentName = process.env.CLAUDE_CODE_AGENT;
+}
+
+// Detect from path (subagents run in /Agents/name/)
+else if (hookData.cwd && hookData.cwd.includes('/Agents/')) {
+  const agentMatch = hookData.cwd.match(/\/agents\/([^\/]+)/);
+  if (agentMatch) agentName = agentMatch[1];
+}
+```
+
+**Session Mapping:** `${PAI_DIR}/agent-sessions.json`
+```json
+{
+  "session-id-abc123": "engineer",
+  "session-id-def456": "researcher"
+}
+```
+
+---
+
+### 4. Observability Integration
+
+**Pattern:** Send event to dashboard → Fail silently if offline
+
+```typescript
+import { sendEventToObservability, getCurrentTimestamp, getSourceApp } from './lib/observability';
+
+await sendEventToObservability({
+  source_app: getSourceApp(),           // 'PAI' or agent name
+  session_id: hookInput.session_id,
+  hook_event_type: 'Stop',
+  timestamp: getCurrentTimestamp(),
+  transcript_path: hookInput.transcript_path,
+  summary: completionMessage,
+  // ... additional fields
+}).catch(() => {
+  // Silently fail - dashboard may not be running
+});
+```
+
+**Dashboard URLs:**
+- Server: `http://localhost:4000`
+- Client: `http://localhost:5173`
+
+---
+
+### 5. Async Non-Blocking Execution
+
+**Pattern:** Hook executes quickly → Launch background processes for slow operations
+
+```typescript
+// update-tab-titles.ts pattern
+// Set immediate tab title (fast)
+execSync(`printf '\\033]0;${titleWithEmoji}\\007' >&2`);
+
+// Launch background process for Haiku summary (slow)
+Bun.spawn(['bun', `${paiDir}/Hooks/update-tab-title.ts`, prompt], {
+  stdout: 'ignore',
+  stderr: 'ignore',
+  stdin: 'ignore'
+});
+
+process.exit(0);  // Exit immediately
+```
+
+**Key Principle:** Hooks must never block Claude Code. Always exit quickly, use background processes for slow work.
+
+---
+
+### 6. Graceful Failure
+
+**Pattern:** Wrap everything in try/catch → Log errors → Exit successfully
+
+```typescript
+async function main() {
+  try {
+    // Hook logic here
+  } catch (error) {
+    // Log but don't fail
+    console.error('Hook error:', error);
+  }
+
+  process.exit(0);  // Always exit 0
+}
+```
+
+**Why:** If hooks crash, Claude Code may freeze. Always exit cleanly.
+
+---
+
+## Creating Custom Hooks
+
+### Step 1: Choose Hook Event
+Decide which event should trigger your hook (SessionStart, Stop, PostToolUse, etc.)
+
+### Step 2: Create Hook Script
+**Location:** `${PAI_DIR}/Hooks/my-custom-hook.ts`
+
+**Template:**
+```typescript
+#!/usr/bin/env bun
+
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  hook_event_name: string;
+  // ... event-specific fields
+}
+
+async function main() {
+  try {
+    // Read stdin
+    const input = await Bun.stdin.text();
+    const data: HookInput = JSON.parse(input);
+
+    // Your hook logic here
+    console.log(`Hook triggered: ${data.hook_event_name}`);
+
+    // Example: Read transcript
+    const fs = require('fs');
+    const transcript = fs.readFileSync(data.transcript_path, 'utf-8');
+
+    // Do something with the data
+
+  } catch (error) {
+    // Log but don't fail
+    console.error('Hook error:', error);
+  }
+
+  process.exit(0);  // Always exit 0
+}
+
+main();
+```
+
+### Step 3: Make Executable
+```bash
+chmod +x ${PAI_DIR}/Hooks/my-custom-hook.ts
+```
+
+### Step 4: Add to settings.json
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PAI_DIR}/Hooks/my-custom-hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Step 5: Test
+```bash
+# Test hook directly
+echo '{"session_id":"test","transcript_path":"/tmp/test.jsonl","hook_event_name":"Stop"}' | bun ${PAI_DIR}/Hooks/my-custom-hook.ts
+```
+
+### Step 6: Restart Claude Code
+Hooks are loaded at startup. Restart to apply changes.
+
+---
+
+## Hook Development Best Practices
+
+### 1. **Fast Execution**
+- Hooks should complete in < 500ms
+- Use background processes for slow work (Haiku API calls, file processing)
+- Exit immediately after launching background work
+
+### 2. **Graceful Failure**
+- Always wrap in try/catch
+- Log errors to stderr (available in hook debug logs)
+- Always `process.exit(0)` - never throw or exit(1)
+
+### 3. **Non-Blocking**
+- Never wait for external services (unless they respond quickly)
+- Use `.catch(() => {})` for async operations
+- Fail silently if optional services are offline
+
+### 4. **Stdin Reading**
+- Use timeout when reading stdin (Claude Code may not send data immediately)
+- Handle empty/invalid input gracefully
+
+```typescript
+const decoder = new TextDecoder();
+const reader = Bun.stdin.stream().getReader();
+
+const timeoutPromise = new Promise<void>((resolve) => {
+  setTimeout(() => resolve(), 500);  // 500ms timeout
+});
+
+await Promise.race([readPromise, timeoutPromise]);
+```
+
+### 5. **File I/O**
+- Check `existsSync()` before reading files
+- Create directories with `{ recursive: true }`
+- Use PST timestamps for consistency
+
+### 6. **Environment Access**
+- All `settings.json` env vars available via `process.env`
+- Use `${PAI_DIR}` in settings.json for portability
+- Access in code via `process.env.PAI_DIR`
+
+### 7. **Observability**
+- Send events to dashboard for visibility
+- Include all relevant metadata (session_id, tool_name, etc.)
+- Use `.catch(() => {})` - dashboard may be offline
+
+---
+
+## Troubleshooting
+
+### Hook Not Running
+
+**Check:**
+1. Is hook script executable? `chmod +x ${PAI_DIR}/Hooks/my-hook.ts`
+2. Is path correct in settings.json? Use `${PAI_DIR}/Hooks/...`
+3. Is settings.json valid JSON? `jq . ${PAI_DIR}/settings.json`
+4. Did you restart Claude Code after editing settings.json?
+
+**Debug:**
+```bash
+# Test hook directly
+echo '{"session_id":"test","transcript_path":"/tmp/test.jsonl","hook_event_name":"Stop"}' | bun ${PAI_DIR}/Hooks/my-hook.ts
+
+# Check hook logs (stderr output)
+tail -f ${PAI_DIR}/Hooks/debug.log  # If you add logging
+```
+
+---
+
+### Hook Hangs/Freezes Claude Code
+
+**Cause:** Hook not exiting (infinite loop, waiting for input, blocking operation)
+
+**Fix:**
+1. Add timeouts to all blocking operations
+2. Ensure `process.exit(0)` is always reached
+3. Use background processes for long operations
+4. Check stdin reading has timeout
+
+**Prevention:**
+```typescript
+// Always use timeout
+setTimeout(() => {
+  console.error('Hook timeout - exiting');
+  process.exit(0);
+}, 5000);  // 5 second max
+```
+
+---
+
+### Voice Notifications Not Working
+
+**Check:**
+1. Is voice server running? `curl http://localhost:8888/health`
+2. Is voice_id correct? See `skills/CORE/SKILL.md` for mappings
+3. Is message format correct? `{"message":"...", "voice_id":"...", "title":"..."}`
+4. Is ElevenLabs API key in `${PAI_DIR}/.env`?
+
+**Debug:**
+```bash
+# Test voice server directly
+curl -X POST http://localhost:8888/notify \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Test message","voice_id":"s3TPKV1kjDlVtZbl4Ksh","title":"Test"}'
+```
+
+**Common Issues:**
+- Wrong voice_id → Silent failure (invalid ID)
+- Voice server offline → Hook continues (graceful failure)
+- No `🎯 COMPLETED:` line → No voice notification extracted
+
+---
+
+### History Not Capturing
+
+**Check:**
+1. Does `${PAI_DIR}/History/` directory exist?
+2. Are structured sections present in response? (`📋 SUMMARY:`, `🎯 COMPLETED:`, etc.)
+3. Is hook actually running? Check `${PAI_DIR}/History/raw-outputs/` for events
+4. File permissions? `ls -la ${PAI_DIR}/History/sessions/`
+
+**Debug:**
+```bash
+# Check recent captures
+ls -lt ${PAI_DIR}/History/sessions/$(date +%Y-%m)/ | head -10
+ls -lt ${PAI_DIR}/History/learnings/$(date +%Y-%m)/ | head -10
+
+# Check raw events
+tail ${PAI_DIR}/History/raw-outputs/$(date +%Y-%m)/$(date +%Y-%m-%d)_all-events.jsonl
+```
+
+**Common Issues:**
+- Missing structured format → No parsing
+- No `🎯 COMPLETED:` line → Capture may fail
+- Learning detection too strict → Adjust `isLearningCapture()` logic
+
+---
+
+### Stop Event Not Firing (CRITICAL KNOWN ISSUE)
+
+**Symptom:** Stop hook configured and working, but Stop events not firing consistently
+
+**Evidence:**
+```bash
+# Check if Stop events fired today
+grep '"event_type":"Stop"' ${PAI_DIR}/History/raw-outputs/$(date +%Y-%m)/$(date +%Y-%m-%d)_all-events.jsonl
+# Result: 0 matches (no Stop events)
+
+# But other hooks ARE working
+grep '"event_type":"PostToolUse"' ${PAI_DIR}/History/raw-outputs/$(date +%Y-%m)/$(date +%Y-%m-%d)_all-events.jsonl
+# Result: 80+ matches (PostToolUse working fine)
+```
+
+**Impact:**
+- Automatic work summaries NOT captured to history (despite Stop hook logic being correct)
+- Learning moments NOT auto-detected
+- Voice notifications from main agent responses NOT sent
+- Manual verification and capture REQUIRED
+
+**Root Cause:**
+- Claude Code event trigger issue (external to hook system)
+- Stop event not being emitted when main agent completes responses
+- Hook configuration is correct, hook script works, event just never fires
+- Other event types (PostToolUse, SessionEnd, UserPromptSubmit) work fine
+
+**Workaround (MANDATORY):**
+
+1. **Added CAPTURE field to response format** (see `${PAI_DIR}/Skills/CORE/SKILL.md`)
+   - MANDATORY field in every response
+   - Forces verification before completing responses
+   - Must document: "Auto-captured" / "Manually saved" / "N/A"
+
+2. **Added MANDATORY VERIFICATION GATE** to file organization section
+   - Before completing valuable work, MUST run verification commands
+   - Check if auto-capture happened (ls -lt history directories)
+   - If not, manually save to appropriate history location
+
+3. **Verification Commands:**
+   ```bash
+   # Check if auto-captured (should happen, but often doesn't due to Stop event bug)
+   ls -lt ${PAI_DIR}/History/sessions/$(date +%Y-%m)/ | head -5
+   ls -lt ${PAI_DIR}/History/learnings/$(date +%Y-%m)/ | head -5
+
+   # If 0 results or doesn't match current work → Manual capture required
+   ```
+
+**Status:** UNRESOLVED (Claude Code issue, not hook configuration)
+**Mitigation:** Structural enforcement via response format (cannot complete valuable work without verification)
+**Tracking:** Documented in `${PAI_DIR}/Skills/CORE/SKILL.md` (History Capture System section)
+
+**Long-term Fix:**
+- Report to Anthropic (Claude Code team) as Stop event reliability issue
+- Monitor future Claude Code updates for fix
+- Keep workaround in place until Stop events fire reliably
+
+---
+
+### Agent Detection Failing
+
+**Check:**
+1. Is `${PAI_DIR}/agent-sessions.json` writable?
+2. Is `[AGENT:type]` tag in `🎯 COMPLETED:` line?
+3. Is agent running from correct directory? (`/Agents/name/`)
+
+**Debug:**
+```bash
+# Check session mappings
+cat ${PAI_DIR}/agent-sessions.json | jq .
+
+# Check subagent-stop debug log
+tail -f ${PAI_DIR}/Hooks/subagent-stop-debug.log
+```
+
+**Fix:**
+- Ensure agents include `[AGENT:type]` in completion line
+- Verify Task tool passes `subagent_type` parameter
+- Check cwd includes `/Agents/` in path
+
+---
+
+### Observability Dashboard Not Receiving Events
+
+**Check:**
+1. Is dashboard server running? `curl http://localhost:4000/health`
+2. Are hooks sending events? Check `sendEventToObservability()` calls
+3. Network issues? `netstat -an | grep 4000`
+
+**Debug:**
+```bash
+# Start dashboard server
+cd ${PAI_DIR}/Skills/system/observability/dashboard/apps/server
+bun run dev
+
+# Check server logs
+# Events should appear in real-time
+```
+
+**Note:** Hooks fail silently if dashboard offline (by design). Not critical for operation.
+
+---
+
+### Context Loading Issues (SessionStart)
+
+**Check:**
+1. Does `${PAI_DIR}/Skills/CORE/SKILL.md` exist?
+2. Is `load-core-context.ts` executable?
+3. Is `PAI_DIR` env variable set correctly?
+
+**Debug:**
+```bash
+# Test context loading directly
+bun ${PAI_DIR}/Hooks/load-core-context.ts
+
+# Should output <system-reminder> with SKILL.md content
+```
+
+**Common Issues:**
+- Subagent sessions loading main context → Fixed (subagent detection in hook)
+- File not found → Check `PAI_DIR` environment variable
+- Permission denied → `chmod +x ${PAI_DIR}/Hooks/load-core-context.ts`
+
+---
+
+## Advanced Topics
+
+### Multi-Hook Execution Order
+
+Hooks in same event execute **sequentially** in order defined in settings.json:
+
+```json
+{
+  "Stop": [
+    {
+      "hooks": [
+        { "command": "${PAI_DIR}/Hooks/stop-hook.ts" },      // Runs first
+        { "command": "${PAI_DIR}/Hooks/capture-all-events.ts" }  // Runs second
+      ]
+    }
+  ]
+}
+```
+
+**Note:** If first hook hangs, second won't run. Keep hooks fast!
+
+---
+
+### Matcher Patterns
+
+`"matcher"` field filters which events trigger hook:
+
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "Bash",  // Only Bash tool executions
+      "hooks": [...]
+    },
+    {
+      "matcher": "*",     // All tool executions
+      "hooks": [...]
+    }
+  ]
+}
+```
+
+**Patterns:**
+- `"*"` - All events
+- `"Bash"` - Specific tool name
+- `""` - Empty (all events, same as `*`)
+
+---
+
+### Hook Data Payloads by Event Type
+
+**SessionStart:**
+```typescript
+{
+  session_id: string;
+  transcript_path: string;
+  hook_event_name: "SessionStart";
+  cwd: string;
+}
+```
+
+**UserPromptSubmit:**
+```typescript
+{
+  session_id: string;
+  transcript_path: string;
+  hook_event_name: "UserPromptSubmit";
+  prompt: string;  // The user's prompt text
+}
+```
+
+**PreToolUse:**
+```typescript
+{
+  session_id: string;
+  transcript_path: string;
+  hook_event_name: "PreToolUse";
+  tool_name: string;
+  tool_input: any;  // Tool parameters
+}
+```
+
+**PostToolUse:**
+```typescript
+{
+  session_id: string;
+  transcript_path: string;
+  hook_event_name: "PostToolUse";
+  tool_name: string;
+  tool_input: any;
+  tool_output: any;  // Tool result
+  error?: string;    // If tool failed
+}
+```
+
+**Stop:**
+```typescript
+{
+  session_id: string;
+  transcript_path: string;
+  hook_event_name: "Stop";
+}
+```
+
+**SubagentStop:**
+```typescript
+{
+  session_id: string;
+  transcript_path: string;
+  hook_event_name: "SubagentStop";
+}
+```
+
+**SessionEnd:**
+```typescript
+{
+  conversation_id: string;  // Note: different field name
+  timestamp: string;
+}
+```
+
+---
+
+## Related Documentation
+
+- **Voice System:** `${PAI_DIR}/voice-server/USAGE.md`
+- **Agent Architecture:** `${PAI_DIR}/Skills/CORE/agent-protocols.md`
+- **History/UOCS:** `${PAI_DIR}/Skills/CORE/history-system.md`
+- **Observability Dashboard:** `${PAI_DIR}/Skills/Observability/`
+
+---
+
+## Quick Reference Card
+
+```
+HOOK LIFECYCLE:
+1. Event occurs (SessionStart, Stop, etc.)
+2. Claude Code writes hook data to stdin
+3. Hook script executes
+4. Hook reads stdin (with timeout)
+5. Hook performs actions (voice, capture, etc.)
+6. Hook exits 0 (always succeeds)
+7. Claude Code continues
+
+KEY FILES:
+${PAI_DIR}/settings.json           Hook configuration
+${PAI_DIR}/Hooks/                  Hook scripts
+${PAI_DIR}/Hooks/lib/observability.ts   Helper library
+${PAI_DIR}/History/raw-outputs/    Event logs (JSONL)
+${PAI_DIR}/History/sessions/       Work summaries
+${PAI_DIR}/History/learnings/      Learning captures
+${PAI_DIR}/agent-sessions.json     Session→Agent mapping
+
+CRITICAL HOOKS:
+stop-hook.ts          Voice + history capture (main agent)
+subagent-stop-hook.ts Voice + history capture (subagents)
+load-core-context.ts  PAI context loading
+capture-all-events.ts Universal event logger
+
+VOICE SERVER:
+URL: http://localhost:8888/notify
+Payload: {"message":"...", "voice_id":"...", "title":"..."}
+Main Voice: s3TPKV1kjDlVtZbl4Ksh (PAI)
+
+OBSERVABILITY:
+Server: http://localhost:4000
+Client: http://localhost:5173
+Events: All hooks send to /events endpoint
+```
+
+---
+
+**Last Updated:** 2025-11-01
+**Status:** Production - All hooks active and tested
+**Maintainer:** {{ENGINEER_NAME}}