xtrm-tools 0.5.24 → 0.5.26

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "0.5.24",
+  "version": "0.5.26",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "main": "./dist/index.js",
   "type": "module",

package/config/hooks.json

@@ -4,6 +4,10 @@
       {
         "script": "beads-compact-restore.mjs",
         "timeout": 5000
+      },
+      {
+        "script": "xtrm-session-logger.mjs",
+        "timeout": 3000
       }
     ],
     "UserPromptSubmit": [
@@ -49,6 +53,10 @@
         "matcher": "Bash|mcp__serena__find_symbol|mcp__serena__get_symbols_overview|mcp__serena__search_for_pattern|mcp__serena__find_referencing_symbols|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|mcp__serena__rename_symbol",
         "script": "gitnexus/gitnexus-hook.cjs",
         "timeout": 10000
+      },
+      {
+        "script": "xtrm-tool-logger.mjs",
+        "timeout": 3000
       }
     ],
     "Stop": [

package/hooks/beads-claim-sync.mjs

@@ -150,7 +150,6 @@ function main() {
         kind: 'bd.claimed',
         outcome: 'allow',
         issueId,
-        message: `Session ${sessionId} claimed issue ${issueId}`,
       });
 
       process.stdout.write(JSON.stringify({
@@ -191,7 +190,6 @@ function main() {
         kind: 'bd.closed',
         outcome: 'allow',
         issueId: closedIssueId,
-        message: `Issue ${closedIssueId} closed`,
       });
     }
     if (commit) {
@@ -200,10 +198,10 @@ function main() {
         runtime: 'claude',
         sessionId,
         layer: 'bd',
-        kind: 'bd.auto_committed',
+        kind: 'bd.committed',
         outcome: commit.ok ? 'allow' : 'block',
         issueId: closedIssueId ?? null,
-        message: commit.message,
+        data: { msg: commit.message },
         extra: { ok: commit.ok },
       });
     }

package/hooks/beads-commit-gate.mjs

@@ -42,7 +42,7 @@ withSafeBdContext(() => {
       runtime: 'claude',
       sessionId: ctx.sessionId,
       layer: 'gate',
-      kind: 'hook.commit_gate.allow',
+      kind: 'gate.commit.allow',
       outcome: 'allow',
       toolName: 'Bash',
       issueId: state?.claimId ?? null,
@@ -57,7 +57,7 @@ withSafeBdContext(() => {
     runtime: 'claude',
     sessionId: ctx.sessionId,
     layer: 'gate',
-    kind: 'hook.commit_gate.block',
+    kind: 'gate.commit.block',
     outcome: 'block',
     toolName: 'Bash',
     issueId: decision.claimed ?? null,

package/hooks/beads-edit-gate.mjs

@@ -31,7 +31,7 @@ if (!_boundary.allow) {
     runtime: 'claude',
     sessionId: resolveSessionId(input),
     layer: 'gate',
-    kind: 'hook.worktree_boundary.block',
+    kind: 'gate.worktree.block',
     outcome: 'block',
     toolName: input.tool_name,
     message: _wbReason,
@@ -55,7 +55,7 @@ withSafeBdContext(() => {
       runtime: 'claude',
       sessionId: ctx.sessionId,
       layer: 'gate',
-      kind: 'hook.edit_gate.allow',
+      kind: 'gate.edit.allow',
       outcome: 'allow',
       toolName: input.tool_name,
       issueId: state?.claimId ?? null,
@@ -73,7 +73,7 @@ withSafeBdContext(() => {
     runtime: 'claude',
     sessionId: ctx.sessionId,
     layer: 'gate',
-    kind: 'hook.edit_gate.block',
+    kind: 'gate.edit.block',
     outcome: 'block',
     toolName: input.tool_name,
     message: reason,

package/hooks/beads-memory-gate.mjs

@@ -41,7 +41,7 @@ if (existsSync(marker)) {
     runtime: 'claude',
     sessionId,
     layer: 'gate',
-    kind: 'hook.memory_gate.acked',
+    kind: 'gate.memory.acked',
     outcome: 'allow',
   });
   process.exit(0);
@@ -72,7 +72,7 @@ logEvent({
   runtime: 'claude',
   sessionId,
   layer: 'gate',
-  kind: 'hook.memory_gate.triggered',
+  kind: 'gate.memory.triggered',
   outcome: 'block',
   issueId: closedIssueId,
   message: memoryMessage,

package/hooks/beads-stop-gate.mjs

@@ -31,7 +31,7 @@ withSafeBdContext(() => {
       runtime: 'claude',
       sessionId: ctx.sessionId,
       layer: 'gate',
-      kind: 'hook.stop_gate.block',
+      kind: 'gate.stop.block',
       outcome: 'block',
       issueId: decision.claimed ?? null,
       message,
@@ -46,7 +46,7 @@ withSafeBdContext(() => {
     runtime: 'claude',
     sessionId: ctx.sessionId,
     layer: 'gate',
-    kind: 'hook.stop_gate.allow',
+    kind: 'session.end',
     outcome: 'allow',
   });
   process.exit(0);

package/hooks/xtrm-logger.mjs

@@ -1,130 +1,123 @@
 #!/usr/bin/env node
-// xtrm-logger.mjs — shared event logger for xtrm hook and bd lifecycle events
+// xtrm-logger.mjs — shared event logger for xtrm hooks
 //
-// Writes to the xtrm_events table in the project's beads Dolt DB.
-// Self-initializing: creates the table on first write if it doesn't exist.
+// 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, runtime: 'claude', sessionId, layer: 'gate', kind: 'hook.edit_gate.block',
-//              outcome: 'block', toolName, issueId, message, extra });
+//   logEvent({ cwd, sessionId, kind: 'gate.edit.allow', outcome: 'allow', toolName, issueId });
 
 import { spawnSync } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 
 // ── Schema ────────────────────────────────────────────────────────────────────
 
-const CREATE_SQL = `CREATE TABLE IF NOT EXISTS xtrm_events (
-  seq         INT           NOT NULL AUTO_INCREMENT,
-  id          VARCHAR(36)   NOT NULL,
-  created_at  DATETIME      NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  runtime     VARCHAR(16)   NOT NULL,
-  session_id  VARCHAR(255)  NOT NULL,
-  worktree    VARCHAR(255)  DEFAULT NULL,
-  layer       VARCHAR(16)   NOT NULL,
-  kind        VARCHAR(64)   NOT NULL,
-  outcome     VARCHAR(8)    NOT NULL,
-  tool_name   VARCHAR(255)  DEFAULT NULL,
-  issue_id    VARCHAR(255)  DEFAULT NULL,
-  message     TEXT          DEFAULT NULL,
-  extra       JSON          DEFAULT NULL,
-  PRIMARY KEY (id),
-  UNIQUE KEY uk_seq (seq),
-  INDEX idx_session (session_id(64)),
-  INDEX idx_kind (kind),
-  INDEX idx_created (created_at)
-)`;
-
-// Migration: add seq column to existing tables that predate this schema version
-const ADD_SEQ_SQL = `ALTER TABLE xtrm_events ADD COLUMN seq INT NOT NULL AUTO_INCREMENT, ADD UNIQUE KEY uk_seq (seq)`;
-
-// ── SQL helpers ───────────────────────────────────────────────────────────────
-
-/**
- * Escape a value for use in a MySQL single-quoted string literal.
- * Returns the quoted string, or NULL for null/undefined.
- */
-function sqlEscape(val) {
-  if (val === null || val === undefined) return 'NULL';
-  const str = String(val)
-    .replace(/\\/g, '\\\\')   // backslash first
-    .replace(/'/g, "''")      // single-quote → doubled
-    .replace(/\0/g, '');      // strip null bytes (invalid in utf8 strings)
-  return `'${str}'`;
+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 bdSql(sql, cwd) {
-  return spawnSync('bd', ['sql', sql], {
-    cwd,
+function sqlExec(dbPath, sql) {
+  return spawnSync('sqlite3', [dbPath, sql], {
     stdio: ['pipe', 'pipe', 'pipe'],
     encoding: 'utf8',
-    timeout: 5000,
+    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 the beads xtrm_events table.
+ * Log an xtrm event to .xtrm/debug.db.
  *
  * @param {object}  params
  * @param {string}  params.cwd         Project working directory (required)
- * @param {string}  params.runtime     'claude' | 'pi'
- * @param {string}  params.sessionId   Claude session UUID or Pi PID string
- * @param {string}  params.layer       'gate' | 'bd'
- * @param {string}  params.kind        e.g. 'hook.edit_gate.block', 'bd.claimed'
- * @param {string}  params.outcome     'allow' | 'block'
- * @param {string}  [params.toolName]  Tool intercepted (gates)
+ * @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 {string}  [params.message]   Full message sent to agent (blocks)
- * @param {object}  [params.extra]     Additional structured data {file, cwd, reason_code, ...}
- *
- * @returns {string|null} The event UUID, or null if logging failed
+ * @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, runtime, sessionId, layer, kind, outcome } = params;
-    if (!cwd || !runtime || !sessionId || !layer || !kind || !outcome) return null;
+    const { cwd, sessionId, kind } = params;
+    if (!cwd || !sessionId || !kind) return;
+
+    const { runtime = 'claude', outcome, toolName, issueId, durationMs, message, extra, data } = params;
 
-    const { toolName, issueId, message, extra } = params;
+    const dbPath = findDbPath(cwd);
+    if (!dbPath) return;
 
-    // Derive worktree name if cwd is inside .xtrm/worktrees/<name>
     const worktreeMatch = cwd.match(/\.xtrm\/worktrees\/([^/]+)/);
     const worktree = worktreeMatch ? worktreeMatch[1] : null;
 
-    const id = randomUUID();
-    const extraJson = extra ? JSON.stringify(extra) : null;
-
-    const cols = 'id, runtime, session_id, worktree, layer, kind, outcome, tool_name, issue_id, message, extra';
-    const vals = [
-      sqlEscape(id),
-      sqlEscape(runtime),
-      sqlEscape(sessionId),
-      sqlEscape(worktree),
-      sqlEscape(layer),
-      sqlEscape(kind),
-      sqlEscape(outcome),
-      sqlEscape(toolName ?? null),
-      sqlEscape(issueId ?? null),
-      sqlEscape(message ?? null),
-      sqlEscape(extraJson),
-    ].join(', ');
-
-    const insertSql = `INSERT INTO xtrm_events (${cols}) VALUES (${vals})`;
-
-    let result = bdSql(insertSql, cwd);
-    if (result.status !== 0) {
-      // Table may not exist yet — create it (includes seq col) and retry once
-      bdSql(CREATE_SQL, cwd);
-      // Migrate existing table if it predates the seq column (fails silently if col exists)
-      bdSql(ADD_SEQ_SQL, cwd);
-      result = bdSql(insertSql, cwd);
+    // 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);
     }
 
-    return result.status === 0 ? id : null;
+    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
-    return null;
   }
 }

package/hooks/xtrm-session-logger.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// xtrm-session-logger.mjs — SessionStart hook
+// Logs session.start to .xtrm/debug.db so every session has a clear entry point.
+
+import { readFileSync } from 'node:fs';
+import { logEvent } from './xtrm-logger.mjs';
+import { resolveCwd, resolveSessionId } from './beads-gate-utils.mjs';
+
+function readInput() {
+  try { return JSON.parse(readFileSync(0, 'utf-8')); } catch { return null; }
+}
+
+const input = readInput();
+if (!input) process.exit(0);
+
+const cwd = resolveCwd(input) || process.cwd();
+const sessionId = resolveSessionId(input);
+
+logEvent({
+  cwd,
+  runtime: 'claude',
+  sessionId,
+  kind: 'session.start',
+  outcome: 'ok',
+});
+
+process.exit(0);

package/hooks/xtrm-tool-logger.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// xtrm-tool-logger.mjs — PostToolUse hook
+// Logs every tool call to .xtrm/debug.db with kind=tool.call.
+// Captures tool-specific context: cmd for Bash, file path for edits, etc.
+
+import { readFileSync } from 'node:fs';
+import { logEvent } from './xtrm-logger.mjs';
+import { resolveCwd, resolveSessionId } from './beads-gate-utils.mjs';
+
+function readInput() {
+  try { return JSON.parse(readFileSync(0, 'utf-8')); } catch { return null; }
+}
+
+function buildData(toolName, toolInput) {
+  if (!toolInput) return null;
+  if (toolName === 'Bash' || toolName === 'bash' || toolName === 'execute_shell_command') {
+    return { cmd: (toolInput.command || '').slice(0, 120) };
+  }
+  if (['Read', 'Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(toolName)) {
+    return toolInput.file_path ? { file: toolInput.file_path } : null;
+  }
+  if (toolName === 'Glob')      return { pattern: toolInput.pattern, path: toolInput.path };
+  if (toolName === 'Grep')      return { pattern: toolInput.pattern, path: toolInput.path };
+  if (toolName === 'WebFetch')  return { url: (toolInput.url   || '').slice(0, 100) };
+  if (toolName === 'WebSearch') return { query: (toolInput.query || '').slice(0, 100) };
+  if (toolName === 'Agent')     return { prompt: (toolInput.prompt || '').slice(0, 80) };
+  return null;
+}
+
+const input = readInput();
+if (!input || input.hook_event_name !== 'PostToolUse') process.exit(0);
+
+const toolName = input.tool_name;
+
+// Skip tools that would create noise or cause recursion
+const SKIP = new Set(['TodoRead', 'TodoWrite', 'Task', 'TaskCreate', 'TaskUpdate', 'TaskGet']);
+if (SKIP.has(toolName)) process.exit(0);
+
+const cwd = resolveCwd(input) || process.cwd();
+const sessionId = resolveSessionId(input);
+const isError = input.tool_response?.is_error === true;
+
+logEvent({
+  cwd,
+  runtime: 'claude',
+  sessionId,
+  kind: 'tool.call',
+  outcome: isError ? 'error' : 'ok',
+  toolName,
+  data: buildData(toolName, input.tool_input),
+});
+
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "0.5.24",
+  "version": "0.5.26",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,8 @@
     "hooks",
     "skills",
     "project-skills",
+    ".claude-plugin",
+    "plugins",
     "!**/__pycache__/**",
     "!**/*.pyc",
     "!project-skills/service-skills-set/.claude/skills/using-service-skills/scripts/test_*.py",
@@ -48,6 +50,8 @@
     "lint": "echo 'No linting configured'",
     "test": "npm test --workspace cli",
     "version": "npm run sync:cli-version && git add cli/package.json",
+    "prepack": "node scripts/prepack-plugin.mjs",
+    "postpack": "node scripts/postpack-plugin.mjs",
     "prepublishOnly": "npm run sync:cli-version && npm run build"
   },
   "engines": {

package/plugins/xtrm-tools/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "xtrm-tools",
+  "version": "0.5.26",
+  "description": "xtrm-tools: dual-runtime workflow enforcement (Claude Code + Pi) — hooks, extensions, skills, and MCP servers",
+  "author": {
+    "name": "jaggers"
+  },
+  "mcpServers": "./.mcp.json"
+}

package/plugins/xtrm-tools/.mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "github-grep": {
+      "type": "http",
+      "url": "https://mcp.grep.app"
+    },
+    "deepwiki": {
+      "type": "http",
+      "url": "https://mcp.deepwiki.com/mcp"
+    },
+    "gitnexus": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "gitnexus", "mcp"],
+      "env": {}
+    }
+  }
+}

package/plugins/xtrm-tools/hooks/README.md

@@ -0,0 +1,61 @@
+# Hooks
+
+Claude Code hooks that extend agent behavior with automated checks, workflow enhancements, and safety guardrails.
+
+## Overview
+
+Hooks intercept specific events in the Claude Code lifecycle. Following architecture decisions in v2.0.0+, the hook ecosystem is designed exclusively for Claude Code.
+
+*Note: In v2.1.15+, several older hooks (`skill-suggestion.py`, `skill-discovery.py`, `gitnexus-impact-reminder.py`, and `type-safety-enforcement.py`) were removed or superseded by native capabilities, CLI commands, and consolidated quality gates.*
+
+## Project Hooks
+
+### gitnexus-hook.cjs
+
+**Purpose**: Enriches tool calls with knowledge graph context via `gitnexus augment`. Now supports Serena tools and uses a deduplication cache for efficiency.
+
+**Trigger**: PostToolUse (Grep|Glob|Bash|Serena edit tools)
+
+## Beads Issue Tracking Gates
+
+The beads gate hooks integrate the `bd` (beads) issue tracker directly into Claude's workflow, ensuring no code changes happen without an active ticket.
+
+**Installation**: Installed with `xtrm install all` or included when `beads`+`dolt` is available.
+
+### Core Gates
+- **`beads-edit-gate.mjs`** (PreToolUse) — Blocks writes/edits without an active issue claim.
+- **`beads-commit-gate.mjs`** (PreToolUse) — Blocks commits with an unresolved session claim.
+- **`beads-stop-gate.mjs`** (Stop) — Blocks session stop while a claim remains open.
+- **`beads-close-memory-prompt.mjs`** (PostToolUse) — Prompts memory handoff after `bd close`.
+
+### Compaction & State Preservation (v2.1.18+)
+- **`beads-pre-compact.mjs`** (PreCompact) — Saves the currently `in_progress` beads state before Claude clears context.
+- **`beads-session-start.mjs`** (SessionStart) — Restores the `in_progress` state when the session restarts after compaction.
+
+*Note: As of v2.1.18+, hook blocking messages are quieted and compacted to save tokens.*
+
+## Hook Timeouts
+
+Adjust hook execution timeouts in `settings.json` if commands take longer than expected:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "hooks": [{
+        "timeout": 5000  // Timeout in milliseconds (5000ms = 5 seconds)
+      }]
+    }]
+  }
+}
+```
+
+## Creating Custom Hooks
+
+To create new project-specific hooks, use the `hook-development` global skill. Follow the canonical structure defined in the `xtrm-tools` core libraries.
+
+For debugging orphaned hooks, use `xtrm clean`.
+
+## Pi Extensions Migration
+
+Core workflow hooks have been migrated to native Pi Extensions for better performance and integration. See the [Pi Extensions Migration Guide](../docs/pi-extensions-migration.md) for details.