xtrm-tools 0.5.25 → 0.5.26

package/plugins/xtrm-tools/hooks/quality-check.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""
+Python Quality Gate - PostToolUse hook for Claude Code.
+Runs ruff (linting/formatting) and mypy (type checking) on edited Python files.
+
+Exit codes:
+  0 - All checks passed
+  1 - Fatal error
+  2 - Blocking errors found (Claude must fix)
+"""
+
+import json
+import os
+import sys
+import subprocess
+import shutil
+from pathlib import Path
+
+# Colors for output
+class Colors:
+    RED = '\x1b[0;31m'
+    GREEN = '\x1b[0;32m'
+    YELLOW = '\x1b[0;33m'
+    BLUE = '\x1b[0;34m'
+    CYAN = '\x1b[0;36m'
+    RESET = '\x1b[0m'
+
+def log_info(msg: str):
+    print(f"{Colors.BLUE}[INFO]{Colors.RESET} {msg}")
+
+def log_error(msg: str):
+    print(f"{Colors.RED}[ERROR]{Colors.RESET} {msg}")
+
+def log_success(msg: str):
+    print(f"{Colors.GREEN}[OK]{Colors.RESET} {msg}")
+
+def log_warning(msg: str):
+    print(f"{Colors.YELLOW}[WARN]{Colors.RESET} {msg}")
+
+def log_debug(msg: str):
+    if os.environ.get('CLAUDE_HOOKS_DEBUG', 'false').lower() == 'true':
+        print(f"{Colors.CYAN}[DEBUG]{Colors.RESET} {msg}")
+
+def find_project_root(file_path: str) -> str:
+    """Find project root by looking for pyproject.toml, setup.py, or .git"""
+    path = Path(file_path).parent
+    while path != path.parent:
+        if (path / 'pyproject.toml').exists() or \
+           (path / 'setup.py').exists() or \
+           (path / '.git').exists():
+            return str(path)
+        path = path.parent
+    return str(path)
+
+def is_python_file(file_path: str) -> bool:
+    """Check if file is a Python source file"""
+    return file_path.endswith('.py') and not file_path.endswith('__init__.py')
+
+
+def has_python_project_config(project_root: str) -> bool:
+    """Return True when Python quality checks are configured for this project."""
+    root = Path(project_root)
+    return (root / 'pyproject.toml').exists() or (root / '.python-version').exists()
+
+def check_ruff(file_path: str, project_root: str, autofix: bool = False) -> tuple[bool, list[str], list[str]]:
+    """
+    Run ruff linting and formatting checks.
+    Returns: (passed, errors, autofixes)
+    """
+    errors = []
+    autofixes = []
+    
+    # Check if ruff is available
+    ruff_path = shutil.which('ruff')
+    if not ruff_path:
+        log_debug('Ruff not found in PATH - skipping ruff checks')
+        return True, errors, autofixes
+    
+    log_info('Running Ruff linting...')
+    
+    # Run ruff check
+    cmd = ['ruff', 'check', '--output-format=full', file_path]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=project_root)
+        
+        if result.returncode != 0:
+            if autofix:
+                log_warning('Ruff issues found, attempting auto-fix...')
+                fix_cmd = ['ruff', 'check', '--fix', file_path]
+                fix_result = subprocess.run(fix_cmd, capture_output=True, text=True, cwd=project_root)
+                
+                if fix_result.returncode == 0:
+                    log_success('Ruff auto-fixed all issues!')
+                    autofixes.append('Ruff auto-fixed linting issues')
+                else:
+                    errors.append(f'Ruff found issues that could not be auto-fixed')
+                    errors.extend(result.stdout.strip().split('\n'))
+            else:
+                errors.append(f'Ruff found linting issues in {os.path.basename(file_path)}')
+                errors.extend(result.stdout.strip().split('\n'))
+        else:
+            log_success('Ruff linting passed')
+            
+    except Exception as e:
+        log_debug(f'Ruff check error: {e}')
+    
+    # Run ruff format check
+    log_info('Running Ruff format check...')
+    format_cmd = ['ruff', 'format', '--check', file_path]
+    try:
+        result = subprocess.run(format_cmd, capture_output=True, text=True, cwd=project_root)
+        
+        if result.returncode != 0:
+            if autofix:
+                log_warning('Ruff format issues found, auto-formatting...')
+                format_fix_cmd = ['ruff', 'format', file_path]
+                format_fix_result = subprocess.run(format_fix_cmd, capture_output=True, text=True, cwd=project_root)
+                
+                if format_fix_result.returncode == 0:
+                    log_success('Ruff auto-formatted the file!')
+                    autofixes.append('Ruff auto-formatted the file')
+                else:
+                    errors.append(f'Ruff formatting issues in {os.path.basename(file_path)}')
+            else:
+                errors.append(f'Ruff formatting issues in {os.path.basename(file_path)}')
+        else:
+            log_success('Ruff formatting correct')
+            
+    except Exception as e:
+        log_debug(f'Ruff format error: {e}')
+    
+    return len(errors) == 0, errors, autofixes
+
+def check_mypy(file_path: str, project_root: str) -> tuple[bool, list[str]]:
+    """
+    Run mypy type checking.
+    Returns: (passed, errors)
+    """
+    errors = []
+    
+    # Check if mypy is available
+    mypy_path = shutil.which('mypy')
+    if not mypy_path:
+        log_debug('Mypy not found in PATH - skipping type checking')
+        return True, errors
+    
+    log_info('Running Mypy type checking...')
+    
+    # Build mypy command with strictness flags
+    # Default: --disallow-untyped-defs catches untyped function parameters
+    # Opt-in: CLAUDE_HOOKS_MYPY_STRICT=true enables full --strict mode
+    mypy_strict = os.environ.get('CLAUDE_HOOKS_MYPY_STRICT', 'false').lower() == 'true'
+    
+    if mypy_strict:
+        cmd = ['mypy', '--strict', '--pretty', file_path]
+        log_debug('Running mypy with --strict (full strictness)')
+    else:
+        cmd = ['mypy', '--disallow-untyped-defs', '--pretty', file_path]
+        log_debug('Running mypy with --disallow-untyped-defs (baseline strictness)')
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=project_root)
+        
+        if result.returncode != 0:
+            errors.append(f'Mypy found type errors in {os.path.basename(file_path)}')
+            if result.stdout:
+                errors.extend(result.stdout.strip().split('\n'))
+            if result.stderr:
+                errors.extend(result.stderr.strip().split('\n'))
+        else:
+            log_success('Mypy type checking passed')
+            
+    except Exception as e:
+        log_debug(f'Mypy error: {e}')
+    
+    return len(errors) == 0, errors
+
+def check_pytest_suggestions(file_path: str, project_root: str):
+    """Suggest running tests if test file exists"""
+    base_name = file_path.replace('.py', '')
+    test_paths = [
+        f'{base_name}_test.py',
+        f'{base_name}_tests.py',
+        f'test_{Path(file_path).name}',
+    ]
+    
+    # Check same directory
+    for test_path in test_paths:
+        if Path(test_path).exists():
+            log_warning(f'💡 Related test found: {os.path.basename(test_path)}')
+            log_warning('   Consider running: pytest')
+            return
+    
+    # Check __tests__ directory
+    tests_dir = Path(file_path).parent / '__tests__'
+    if tests_dir.exists():
+        for test_path in tests_dir.glob(f'test_{Path(file_path).name}'):
+            log_warning(f'💡 Related test found: __tests__/{test_path.name}')
+            log_warning('   Consider running: pytest')
+            return
+    
+    log_warning(f'💡 No test file found for {os.path.basename(file_path)}')
+
+def print_summary(errors: list[str], autofixes: list[str]):
+    """Print summary of errors and autofixes"""
+    if autofixes:
+        print(f'\n{Colors.BLUE}═══ Auto-fixes Applied ═══{Colors.RESET}')
+        for fix in autofixes:
+            print(f'{Colors.GREEN}✨{Colors.RESET} {fix}')
+        print(f'{Colors.GREEN}Automatically fixed {len(autofixes)} issue(s)!{Colors.RESET}')
+    
+    if errors:
+        print(f'\n{Colors.BLUE}═══ Quality Check Summary ═══{Colors.RESET}')
+        for error in errors:
+            print(f'{Colors.RED}❌{Colors.RESET} {error}')
+        print(f'\n{Colors.RED}Found {len(errors)} issue(s) that MUST be fixed!{Colors.RESET}')
+        print(f'{Colors.RED}══════════════════════════════════════{Colors.RESET}')
+        print(f'{Colors.RED}❌ ALL ISSUES ARE BLOCKING ❌{Colors.RESET}')
+        print(f'{Colors.RED}══════════════════════════════════════{Colors.RESET}')
+        print(f'{Colors.RED}Fix EVERYTHING above until all checks are ✅ GREEN{Colors.RESET}')
+
+def parse_json_input() -> dict:
+    """Parse JSON input from stdin"""
+    input_data = sys.stdin.read().strip()
+    
+    if not input_data:
+        log_warning('No JSON input provided.')
+        print(f'\n{Colors.YELLOW}👉 Hook executed but no input to process.{Colors.RESET}')
+        sys.exit(0)
+    
+    try:
+        return json.loads(input_data)
+    except json.JSONDecodeError as e:
+        log_error(f'Failed to parse JSON: {e}')
+        sys.exit(1)
+
+def extract_file_path(input_data: dict) -> str | None:
+    """Extract file path from tool input, including Serena relative_path."""
+    tool_input = input_data.get('tool_input', {})
+    file_path = (
+        tool_input.get('file_path')
+        or tool_input.get('path')
+        or tool_input.get('relative_path')
+    )
+    if not file_path:
+        return None
+
+    # Serena tools pass relative_path relative to the project root.
+    if not os.path.isabs(file_path):
+        project_root = os.environ.get('CLAUDE_PROJECT_DIR') or os.getcwd()
+        return str(Path(project_root) / file_path)
+
+    return file_path
+
+def main():
+    """Main entry point"""
+    print('')
+    print(f'📦 Python Quality Check - Starting...')
+    print('─────────────────────────────────────')
+    
+    # Parse input
+    input_data = parse_json_input()
+    file_path = extract_file_path(input_data)
+    
+    if not file_path:
+        log_warning('No file path found in JSON input.')
+        print(f'\n{Colors.YELLOW}👉 No file to check - tool may not be file-related.{Colors.RESET}')
+        sys.exit(0)
+    
+    # Check if file exists
+    if not Path(file_path).exists():
+        log_info(f'File does not exist: {file_path}')
+        print(f'\n{Colors.YELLOW}👉 File skipped - doesn\'t exist.{Colors.RESET}')
+        sys.exit(0)
+    
+    # Skip non-Python files
+    if not is_python_file(file_path):
+        log_info(f'Skipping non-Python file: {file_path}')
+        print(f'\n{Colors.GREEN}✅ No checks needed for {os.path.basename(file_path)}{Colors.RESET}')
+        sys.exit(0)
+    
+    # Update header
+    print('')
+    print(f'🔍 Validating: {os.path.basename(file_path)}')
+    print('─────────────────────────────────────')
+    log_info(f'Checking: {file_path}')
+    
+    # Find project root
+    project_root = find_project_root(file_path)
+    log_debug(f'Project root: {project_root}')
+
+    if not has_python_project_config(project_root):
+        log_info('No pyproject.toml or .python-version found - skipping Python quality checks')
+        print(f'\n{Colors.GREEN}✅ No Python project config detected; skipping checks for {os.path.basename(file_path)}{Colors.RESET}')
+        sys.exit(0)
+    
+    # Get config from environment
+    autofix = os.environ.get('CLAUDE_HOOKS_AUTOFIX', 'true').lower() == 'true'
+    ruff_enabled = os.environ.get('CLAUDE_HOOKS_RUFF_ENABLED', 'true').lower() != 'false'
+    mypy_enabled = os.environ.get('CLAUDE_HOOKS_MYPY_ENABLED', 'true').lower() != 'false'
+    
+    all_errors = []
+    all_autofixes = []
+    
+    # Run ruff checks
+    if ruff_enabled:
+        ruff_passed, ruff_errors, ruff_autofixes = check_ruff(file_path, project_root, autofix)
+        all_errors.extend(ruff_errors)
+        all_autofixes.extend(ruff_autofixes)
+    
+    # Run mypy checks
+    if mypy_enabled:
+        mypy_passed, mypy_errors = check_mypy(file_path, project_root)
+        all_errors.extend(mypy_errors)
+    
+    # Print summary
+    print_summary(all_errors, all_autofixes)
+    
+    # Exit with appropriate code
+    if all_errors:
+        print(f'\n{Colors.RED}🛑 FAILED - Fix issues in your edited file! 🛑{Colors.RESET}')
+        print(f'{Colors.CYAN}💡 CLAUDE.md CHECK:{Colors.RESET}')
+        print(f'{Colors.CYAN}  → What CLAUDE.md pattern would have prevented this?{Colors.RESET}')
+        print(f'{Colors.YELLOW}📋 NEXT STEPS:{Colors.RESET}')
+        print(f'{Colors.YELLOW}  1. Fix the issues listed above{Colors.RESET}')
+        print(f'{Colors.YELLOW}  2. The hook will run again automatically{Colors.RESET}')
+        print(f'{Colors.YELLOW}  3. Continue once all checks pass{Colors.RESET}')
+        sys.exit(2)
+    else:
+        print(f'\n{Colors.GREEN}✅ Quality check passed for {os.path.basename(file_path)}{Colors.RESET}')
+        if all_autofixes:
+            print(f'\n{Colors.YELLOW}👉 File quality verified. Auto-fixes applied. Continue with your task.{Colors.RESET}')
+        else:
+            print(f'\n{Colors.YELLOW}👉 File quality verified. Continue with your task.{Colors.RESET}')
+        
+        # Suggest tests
+        check_pytest_suggestions(file_path, project_root)
+        
+        sys.exit(0)
+
+if __name__ == '__main__':
+    try:
+        main()
+    except Exception as e:
+        log_error(f'Fatal error: {e}')
+        sys.exit(1)

package/plugins/xtrm-tools/hooks/statusline.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// statusline.mjs — Claude Code statusLine for xt claude sessions
+// Line 1: XTRM  dim(model [xx%])  hostname  bold(dir)  dim(branch (status))  dim((venv))
+// Line 2: ◐ italic(claim title)  OR  ○ bold(N) open  — no background
+//
+// Colors: bold/dim/italic only — no explicit fg/bg, adapts to dark & light themes.
+// State: .xtrm/statusline-claim (written by beads-claim-sync.mjs)
+// Cache: /tmp per cwd, 5s TTL
+
+import { execSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, basename, relative } from 'node:path';
+import { tmpdir, hostname } from 'node:os';
+import { createHash } from 'node:crypto';
+
+// Claude Code passes statusline context as JSON on stdin
+let ctx = {};
+try { ctx = JSON.parse(readFileSync(0, 'utf8')); } catch {}
+
+const cwd = ctx?.workspace?.current_dir ?? process.cwd();
+const cacheKey = createHash('md5').update(cwd).digest('hex').slice(0, 8);
+const CACHE_FILE = join(tmpdir(), `xtrm-sl-${cacheKey}.json`);
+const CACHE_TTL = 5000;
+
+function run(cmd) {
+  try {
+    return execSync(cmd, { encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'], timeout: 2000 }).trim();
+  } catch { return null; }
+}
+
+function getCached() {
+  try {
+    const c = JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
+    if (Date.now() - c.ts < CACHE_TTL) return c.data;
+  } catch {}
+  return null;
+}
+
+function setCache(data) {
+  try { writeFileSync(CACHE_FILE, JSON.stringify({ ts: Date.now(), data })); } catch {}
+}
+
+// ANSI — bold/dim/italic only; no explicit fg/bg colors
+const R  = '\x1b[0m';
+const B  = '\x1b[1m';   // bold on
+const B_ = '\x1b[22m';  // bold off (normal intensity)
+const D  = '\x1b[2m';   // dim on
+const I  = '\x1b[3m';   // italic on
+const I_ = '\x1b[23m';  // italic off
+
+let data = getCached();
+if (!data) {
+  // Model + token %
+  const modelId = ctx?.model?.display_name ?? ctx?.model?.id ?? null;
+  const pct = ctx?.context_window?.used_percentage;
+  const modelStr = modelId ? `${modelId}${pct != null ? ` [${Math.round(pct)}%]` : ''}` : null;
+
+  // Short hostname
+  const host = hostname().split('.')[0];
+
+  // Directory — repo-relative like the global script
+  const repoRoot = run('git rev-parse --show-toplevel');
+  let displayDir;
+  if (repoRoot) {
+    const rel = relative(repoRoot, cwd) || '.';
+    displayDir = rel === '.' ? basename(repoRoot) : `${basename(repoRoot)}/${rel}`;
+  } else {
+    displayDir = cwd.replace(process.env.HOME ?? '', '~');
+  }
+
+  // Branch + git status indicators
+  let branch = null;
+  let gitStatus = '';
+  if (repoRoot) {
+    branch = run('git -c core.useBuiltinFSMonitor=false branch --show-current') || run('git rev-parse --short HEAD');
+    const porcelain = run('git -c core.useBuiltinFSMonitor=false --no-optional-locks status --porcelain') ?? '';
+    let modified = false, staged = false, deleted = false;
+    for (const l of porcelain.split('\n').filter(Boolean)) {
+      if (/^ M|^AM|^MM/.test(l)) modified = true;
+      if (/^A |^M /.test(l)) staged = true;
+      if (/^ D|^D /.test(l)) deleted = true;
+    }
+    let st = (modified ? '*' : '') + (staged ? '+' : '') + (deleted ? '-' : '');
+    const ab = run('git -c core.useBuiltinFSMonitor=false --no-optional-locks rev-list --left-right --count @{upstream}...HEAD');
+    if (ab) {
+      const [behind, ahead] = ab.split(/\s+/).map(Number);
+      if (ahead > 0 && behind > 0) st += '↕';
+      else if (ahead > 0) st += '↑';
+      else if (behind > 0) st += '↓';
+    }
+    if (st) gitStatus = `(${st})`;
+  }
+
+  // Python venv
+  const venv = process.env.VIRTUAL_ENV ? `(${basename(process.env.VIRTUAL_ENV)})` : null;
+
+  // Beads
+  let claimId = null;
+  let claimTitle = null;
+  let openCount = 0;
+  if (existsSync(join(cwd, '.beads'))) {
+    const claimFile = join(cwd, '.xtrm', 'statusline-claim');
+    claimId = existsSync(claimFile) ? (readFileSync(claimFile, 'utf8').trim() || null) : null;
+    if (claimId) {
+      try {
+        const raw = run(`bd show ${claimId} --json`);
+        claimTitle = raw ? (JSON.parse(raw)?.[0]?.title ?? null) : null;
+      } catch {}
+    }
+    if (!claimTitle) {
+      const m = run('bd list')?.match(/\((\d+)\s+open/);
+      if (m) openCount = parseInt(m[1], 10);
+    }
+  }
+
+  data = { modelStr, host, displayDir, branch, gitStatus, venv, claimId, claimTitle, openCount };
+  setCache(data);
+}
+
+const { modelStr, host, displayDir, branch, gitStatus, venv, claimId, claimTitle, openCount } = data;
+
+// Line 1 — matches global format, XTRM prepended
+const parts = [`${B}XTRM${B_}`];
+if (modelStr) parts.push(`${D}${modelStr}${R}`);
+parts.push(host);
+if (displayDir) parts.push(`${B}${displayDir}${B_}`);
+if (branch) parts.push(`${D}${[branch, gitStatus].filter(Boolean).join(' ')}${R}`);
+if (venv) parts.push(`${D}${venv}${R}`);
+const line1 = parts.join(' ');
+
+// Line 2 — no background; open count bold
+let line2;
+if (claimTitle) {
+  const cols = process.stdout.columns || 80;
+  const prefix = ` ◐ ${claimId} `;
+  const prefixLen = prefix.replace(/\x1b\[[0-9;]*m/g, '').length;
+  const maxLen = cols - prefixLen - 1;
+  const t = claimTitle.length > maxLen ? claimTitle.slice(0, maxLen - 1) + '…' : claimTitle;
+  line2 = `${prefix}${I}${t}${I_}`;
+} else {
+  line2 = ` ○ ${openCount > 0 ? `${B}${openCount}${B_} open` : 'no open issues'}`;
+}
+
+process.stdout.write(line1 + '\n' + line2 + '\n');
+process.exit(0);

package/plugins/xtrm-tools/hooks/using-xtrm-reminder.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// using-xtrm-reminder.mjs — Claude Code SessionStart hook
+// Reads skills/using-xtrm/SKILL.md and injects it as additionalSystemPrompt
+// so the agent starts every session already oriented on the xtrm workflow.
+// Exit 0 in all paths (fail open).
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+let input;
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+if (!pluginRoot) process.exit(0);
+
+const skillPath = join(pluginRoot, 'skills', 'using-xtrm', 'SKILL.md');
+let content;
+try {
+  content = readFileSync(skillPath, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+// Strip YAML frontmatter (--- ... ---\n)
+content = content.replace(/^---[\s\S]*?---\n/, '').trim();
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalSystemPrompt: content,
+    },
+  }) + '\n',
+);
+process.exit(0);

package/plugins/xtrm-tools/hooks/worktree-boundary.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// worktree-boundary.mjs — Claude Code PreToolUse hook
+// Blocks Write/Edit when the target file is outside the active worktree root.
+// Only active when session cwd is inside .xtrm/worktrees/<name>.
+// Fail-open: any unexpected error allows the edit through.
+//
+// Installed by: xtrm install
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const filePath = input?.tool_input?.file_path;
+if (!filePath) process.exit(0);
+
+// Detect worktree root from cwd
+const m = cwd.match(/^(.+\/\.xtrm\/worktrees\/[^/]+)/);
+if (!m) process.exit(0); // not in a worktree — no constraint
+
+const worktreeRoot = m[1];
+const abs = resolve(cwd, filePath);
+
+if (abs === worktreeRoot || abs.startsWith(worktreeRoot + '/')) process.exit(0);
+
+process.stdout.write(JSON.stringify({
+  decision: 'block',
+  reason: `🚫 Edit outside worktree boundary.\n  File:    ${abs}\n  Allowed: ${worktreeRoot}\n\n  All edits must stay within the active worktree.`,
+}));
+process.stdout.write('\n');
+process.exit(0);

package/plugins/xtrm-tools/hooks/xtrm-logger.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// xtrm-logger.mjs — shared event logger for xtrm hooks
+//
+// Writes to .xtrm/debug.db (SQLite WAL) in the project root.
+// Self-initializing: creates the DB and table on first write.
+// Fails completely silently — logging NEVER affects hook behavior.
+//
+// Usage (from any hook):
+//   import { logEvent } from './xtrm-logger.mjs';
+//   logEvent({ cwd, sessionId, kind: 'gate.edit.allow', outcome: 'allow', toolName, issueId });
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+// ── Schema ────────────────────────────────────────────────────────────────────
+
+const INIT_SQL = `
+PRAGMA journal_mode=WAL;
+PRAGMA busy_timeout=5000;
+CREATE TABLE IF NOT EXISTS events (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts          INTEGER NOT NULL,
+  session_id  TEXT    NOT NULL,
+  runtime     TEXT    NOT NULL,
+  worktree    TEXT,
+  kind        TEXT    NOT NULL,
+  tool_name   TEXT,
+  outcome     TEXT,
+  issue_id    TEXT,
+  duration_ms INTEGER,
+  data        TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_ts      ON events(ts);
+CREATE INDEX IF NOT EXISTS idx_session ON events(session_id);
+CREATE INDEX IF NOT EXISTS idx_kind    ON events(kind);
+`;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function findDbPath(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(dir, '.beads'))) {
+      return join(dir, '.xtrm', 'debug.db');
+    }
+    const parent = join(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null; // No beads project found — silently skip logging
+}
+
+function sqlExec(dbPath, sql) {
+  return spawnSync('sqlite3', [dbPath, sql], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    timeout: 3000,
+  });
+}
+
+function ensureDb(dbPath) {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  sqlExec(dbPath, INIT_SQL);
+}
+
+function sqlEsc(val) {
+  if (val === null || val === undefined) return 'NULL';
+  return `'${String(val).replace(/'/g, "''")}'`;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Log an xtrm event to .xtrm/debug.db.
+ *
+ * @param {object}  params
+ * @param {string}  params.cwd         Project working directory (required)
+ * @param {string}  params.sessionId   Session UUID or Pi PID string (required)
+ * @param {string}  params.kind        Dot-separated kind: 'gate.edit.allow', 'tool.call', 'bd.claimed', etc. (required)
+ * @param {string}  [params.runtime]   'claude' | 'pi'  (default: 'claude')
+ * @param {string}  [params.outcome]   'allow' | 'block' | 'ok' | 'error'
+ * @param {string}  [params.toolName]  Tool name for gate / tool.call events
+ * @param {string}  [params.issueId]   Linked beads issue ID
+ * @param {number}  [params.durationMs] Tool call duration
+ * @param {object}  [params.data]      Structured context (file, cmd, reason, etc.)
+ * @param {string}  [params.message]   Legacy: message string (merged into data.msg)
+ * @param {object}  [params.extra]     Legacy: extra object (merged into data)
+ */
+export function logEvent(params) {
+  try {
+    const { cwd, sessionId, kind } = params;
+    if (!cwd || !sessionId || !kind) return;
+
+    const { runtime = 'claude', outcome, toolName, issueId, durationMs, message, extra, data } = params;
+
+    const dbPath = findDbPath(cwd);
+    if (!dbPath) return;
+
+    const worktreeMatch = cwd.match(/\.xtrm\/worktrees\/([^/]+)/);
+    const worktree = worktreeMatch ? worktreeMatch[1] : null;
+
+    // Merge message/extra/data into a single JSON string
+    let dataStr = null;
+    if (data !== null && data !== undefined) {
+      dataStr = typeof data === 'string' ? data : JSON.stringify(data);
+    } else if (message || extra) {
+      const merged = { ...(message ? { msg: message } : {}), ...(extra || {}) };
+      if (Object.keys(merged).length > 0) dataStr = JSON.stringify(merged);
+    }
+
+    const ts = Date.now();
+    const sql = `INSERT INTO events (ts,session_id,runtime,worktree,kind,tool_name,outcome,issue_id,duration_ms,data) VALUES (${ts},${sqlEsc(sessionId)},${sqlEsc(runtime)},${sqlEsc(worktree)},${sqlEsc(kind)},${sqlEsc(toolName ?? null)},${sqlEsc(outcome ?? null)},${sqlEsc(issueId ?? null)},${durationMs ?? 'NULL'},${sqlEsc(dataStr)})`;
+
+    let result = sqlExec(dbPath, sql);
+    if (result.status !== 0) {
+      ensureDb(dbPath);
+      result = sqlExec(dbPath, sql);
+    }
+  } catch {
+    // Silently swallow all errors — logging never affects hook behavior
+  }
+}