xtrm-tools 0.5.25 → 0.5.26

package/cli/package.json

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

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) {
@@ -203,7 +201,7 @@ function main() {
         kind: 'bd.committed',
         outcome: commit.ok ? 'allow' : 'block',
         issueId: closedIssueId ?? null,
-        message: commit.message,
+        data: { msg: commit.message },
         extra: { ok: commit.ok },
       });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "0.5.25",
+  "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.

package/plugins/xtrm-tools/hooks/beads-claim-sync.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// beads-claim-sync — PostToolUse hook
+// bd update --claim → set kv claim
+// bd close         → auto-commit staged changes, set closed-this-session kv for memory gate
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, existsSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveSessionId } from './beads-gate-utils.mjs';
+import { logEvent } from './xtrm-logger.mjs';
+
+function readInput() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function isBeadsProject(cwd) {
+  return existsSync(join(cwd, '.beads'));
+}
+
+function isShellTool(toolName) {
+  return toolName === 'Bash' || toolName === 'bash' || toolName === 'execute_shell_command';
+}
+
+function commandSucceeded(payload) {
+  const tr = payload?.tool_response ?? payload?.tool_result ?? payload?.result;
+  if (!tr || typeof tr !== 'object') return true;
+
+  if (tr.success === false) return false;
+  if (tr.error) return false;
+
+  const numeric = [tr.exit_code, tr.exitCode, tr.status, tr.returncode].find((v) => Number.isInteger(v));
+  if (typeof numeric === 'number' && numeric !== 0) return false;
+
+  return true;
+}
+
+function runGit(args, cwd, timeout = 8000) {
+  return spawnSync('git', args, {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    timeout,
+  });
+}
+
+function runBd(args, cwd, timeout = 5000) {
+  return spawnSync('bd', args, {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    timeout,
+  });
+}
+
+function hasGitChanges(cwd) {
+  const result = runGit(['status', '--porcelain'], cwd);
+  if (result.status !== 0) return false;
+  return result.stdout.trim().length > 0;
+}
+
+function getCloseReason(cwd, issueId, command) {
+  // 1. Parse --reason "..." from the command itself (fastest, no extra call)
+  const reasonMatch = command.match(/--reason[=\s]+["']([^"']+)["']/);
+  if (reasonMatch) return reasonMatch[1].trim();
+
+  // 2. Fall back to bd show <id> --json
+  const show = runBd(['show', issueId, '--json'], cwd);
+  if (show.status === 0 && show.stdout) {
+    try {
+      const parsed = JSON.parse(show.stdout);
+      const reason = parsed?.[0]?.close_reason;
+      if (typeof reason === 'string' && reason.trim().length > 0) return reason.trim();
+    } catch { /* fall through */ }
+  }
+
+  return `Close ${issueId}`;
+}
+
+function stageUntracked(cwd) {
+  const result = runGit(['ls-files', '--others', '--exclude-standard'], cwd);
+  if (result.status !== 0) return;
+  const untracked = result.stdout.trim().split('\n').filter(Boolean);
+  if (untracked.length === 0) return;
+  runGit(['add', '--', ...untracked], cwd);
+}
+
+function autoCommit(cwd, issueId, command) {
+  if (!hasGitChanges(cwd)) {
+    return { ok: true, message: 'No changes detected — auto-commit skipped.' };
+  }
+
+  stageUntracked(cwd);
+
+  const reason = getCloseReason(cwd, issueId, command);
+  const commitMessage = `${reason} (${issueId})`;
+  const result = runGit(['commit', '-am', commitMessage], cwd, 15000);
+  if (result.status !== 0) {
+    const err = (result.stderr || result.stdout || '').trim();
+    return { ok: false, message: `Auto-commit failed: ${err || 'unknown error'}` };
+  }
+
+  return { ok: true, message: `Auto-committed: \`${commitMessage}\`` };
+}
+
+
+function main() {
+  const input = readInput();
+  if (!input || input.hook_event_name !== 'PostToolUse') process.exit(0);
+  if (!isShellTool(input.tool_name)) process.exit(0);
+
+  const cwd = input.cwd || process.cwd();
+  if (!isBeadsProject(cwd)) process.exit(0);
+
+  const command = input.tool_input?.command || '';
+  const sessionId = resolveSessionId(input);
+
+  // Auto-claim: bd update <id> --claim (fire regardless of exit code — bd returns 1 for "already in_progress")
+  if (/\bbd\s+update\b/.test(command) && /--claim\b/.test(command)) {
+    const match = command.match(/\bbd\s+update\s+(\S+)/);
+    if (match) {
+      const issueId = match[1];
+      const result = spawnSync('bd', ['kv', 'set', `claimed:${sessionId}`, issueId], {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 5000,
+      });
+
+      if (result.status !== 0) {
+        const err = (result.stderr || result.stdout || '').toString().trim();
+        if (err) process.stderr.write(`Beads claim sync warning: ${err}\n`);
+        process.exit(0);
+      }
+
+      // Write claim state for statusline
+      try {
+        const xtrmDir = join(cwd, '.xtrm');
+        mkdirSync(xtrmDir, { recursive: true });
+        writeFileSync(join(xtrmDir, 'statusline-claim'), issueId);
+      } catch { /* non-fatal */ }
+
+      logEvent({
+        cwd,
+        runtime: 'claude',
+        sessionId,
+        layer: 'bd',
+        kind: 'bd.claimed',
+        outcome: 'allow',
+        issueId,
+      });
+
+      process.stdout.write(JSON.stringify({
+        additionalContext: `\n✅ **Beads**: Session \`${sessionId}\` claimed issue \`${issueId}\`.`,
+      }));
+      process.stdout.write('\n');
+      process.exit(0);
+    }
+  }
+
+  // On bd close: auto-commit staged changes, then mark closed-this-session for memory gate
+  if (/\bbd\s+close\b/.test(command) && commandSucceeded(input)) {
+    const match = command.match(/\bbd\s+close\s+(\S+)/);
+    const closedIssueId = match?.[1];
+
+    // Auto-commit before marking the gate (no-op if clean)
+    const commit = closedIssueId ? autoCommit(cwd, closedIssueId, command) : null;
+
+    // Clear claim state for statusline
+    try { unlinkSync(join(cwd, '.xtrm', 'statusline-claim')); } catch { /* ok if missing */ }
+
+    // Mark this issue as closed this session (memory gate reads this)
+    if (closedIssueId) {
+      spawnSync('bd', ['kv', 'set', `closed-this-session:${sessionId}`, closedIssueId], {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 5000,
+      });
+    }
+
+    // Log bd lifecycle events
+    if (closedIssueId) {
+      logEvent({
+        cwd,
+        runtime: 'claude',
+        sessionId,
+        layer: 'bd',
+        kind: 'bd.closed',
+        outcome: 'allow',
+        issueId: closedIssueId,
+      });
+    }
+    if (commit) {
+      logEvent({
+        cwd,
+        runtime: 'claude',
+        sessionId,
+        layer: 'bd',
+        kind: 'bd.committed',
+        outcome: commit.ok ? 'allow' : 'block',
+        issueId: closedIssueId ?? null,
+        data: { msg: commit.message },
+        extra: { ok: commit.ok },
+      });
+    }
+
+    const commitLine = commit
+      ? `\n${commit.ok ? '✅' : '⚠️'} **Session Flow**: ${commit.message}`
+      : '';
+
+    process.stdout.write(JSON.stringify({
+      additionalContext: `\n🔓 **Beads**: Issue closed.${commitLine}\nEvaluate insights, then acknowledge:\n  \`bd remember "<insight>"\` (or note "nothing")\n  \`touch .beads/.memory-gate-done\``,
+    }));
+    process.stdout.write('\n');
+    process.exit(0);
+  }
+
+  process.exit(0);
+}
+
+main();

package/plugins/xtrm-tools/hooks/beads-commit-gate.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// beads-commit-gate — Claude Code PreToolUse hook
+// Blocks `git commit` when this session still has an unclosed claim in bd kv.
+// Falls back to global in_progress check when session_id is unavailable.
+// Forces: close issues first, THEN commit.
+// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
+//
+// Installed by: xtrm install
+
+import {
+  readHookInput,
+  resolveSessionContext,
+  resolveClaimAndWorkState,
+  decideCommitGate,
+} from './beads-gate-core.mjs';
+import { withSafeBdContext } from './beads-gate-utils.mjs';
+import { commitBlockMessage } from './beads-gate-messages.mjs';
+import { logEvent } from './xtrm-logger.mjs';
+
+const input = readHookInput();
+if (!input) process.exit(0);
+
+if ((input.tool_name ?? '') !== 'Bash') process.exit(0);
+
+const command = input.tool_input?.command ?? '';
+// Strip quoted strings to avoid matching patterns inside --reason "..." or similar args
+const commandUnquoted = command.replace(/'[^']*'|"[^"]*"/g, '');
+
+withSafeBdContext(() => {
+  const ctx = resolveSessionContext(input);
+  if (!ctx || !ctx.isBeadsProject) process.exit(0);
+
+  // Only intercept git commit for the claim-gate check
+  if (!/\bgit\s+commit\b/.test(commandUnquoted)) process.exit(0);
+
+  const state = resolveClaimAndWorkState(ctx);
+  const decision = decideCommitGate(ctx, state);
+
+  if (decision.allow) {
+    logEvent({
+      cwd: ctx.cwd,
+      runtime: 'claude',
+      sessionId: ctx.sessionId,
+      layer: 'gate',
+      kind: 'gate.commit.allow',
+      outcome: 'allow',
+      toolName: 'Bash',
+      issueId: state?.claimId ?? null,
+    });
+    process.exit(0);
+  }
+
+  // Block with structured decision
+  const reason = commitBlockMessage(decision.summary, decision.claimed);
+  logEvent({
+    cwd: ctx.cwd,
+    runtime: 'claude',
+    sessionId: ctx.sessionId,
+    layer: 'gate',
+    kind: 'gate.commit.block',
+    outcome: 'block',
+    toolName: 'Bash',
+    issueId: decision.claimed ?? null,
+    message: reason,
+    extra: { reason_code: decision.reason },
+  });
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  process.stdout.write('\n');
+  process.exit(0);
+});

package/plugins/xtrm-tools/hooks/beads-compact-restore.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Claude Code SessionStart hook — restore in_progress beads issues after context compaction.
+// Reads .beads/.last_active (written by beads-compact-save.mjs), reinstates statuses,
+// restores session state file, deletes the marker, and injects a brief agent context message.
+// Exit 0 in all paths (informational only).
+
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync, unlinkSync } from 'node:fs';
+import path 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 lastActivePath = path.join(cwd, '.beads', '.last_active');
+
+if (!existsSync(lastActivePath)) process.exit(0);
+
+let ids = [];
+
+try {
+  const raw = readFileSync(lastActivePath, 'utf8').trim();
+  if (raw.startsWith('{')) {
+    const parsed = JSON.parse(raw);
+    ids = Array.isArray(parsed.ids) ? parsed.ids.filter(Boolean) : [];
+  } else {
+    // Backward compatibility: legacy newline format
+    ids = raw.split('\n').filter(Boolean);
+  }
+} catch {
+  // If file is malformed, just delete and continue fail-open.
+}
+
+// Clean up regardless of whether restore succeeds
+unlinkSync(lastActivePath);
+
+let restored = 0;
+for (const id of ids) {
+  try {
+    execSync(`bd update ${id} --status in_progress`, {
+      encoding: 'utf8',
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    });
+    restored++;
+  } catch {
+    // ignore — issue may no longer exist
+  }
+}
+
+if (restored > 0) {
+  const lines = [`Restored ${restored} in_progress issue${restored === 1 ? '' : 's'} from last session before compaction.`];
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalSystemPrompt: `${lines.join(' ')} Check \`bd list\` for details.`,
+      },
+    }) + '\n',
+  );
+}
+
+process.exit(0);

package/plugins/xtrm-tools/hooks/beads-compact-save.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Claude Code PreCompact hook — save in_progress beads issues before context is compacted.
+// Writes a compact bundle to .beads/.last_active for restore hook.
+// Bundle includes issue IDs and xtrm session state when available.
+// Exit 0 in all paths (informational only).
+
+import { execSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import path 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 beadsDir = path.join(cwd, '.beads');
+
+if (!existsSync(beadsDir)) process.exit(0);
+
+let output = '';
+try {
+  output = execSync('bd list --status=in_progress', {
+    encoding: 'utf8',
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 8000,
+  }).trim();
+} catch {
+  process.exit(0);
+}
+
+// Parse issue IDs — lines like "◐ proj-abc123 ● P1 Title"
+const ids = [];
+for (const line of output.split('\n')) {
+  const match = line.trim().match(/^[○◐●✓❄]\s+([\w-]+)\s/u);
+  if (match) ids.push(match[1]);
+}
+
+const bundle = {
+  ids,
+  savedAt: new Date().toISOString(),
+};
+
+if (bundle.ids.length === 0) process.exit(0);
+
+writeFileSync(path.join(beadsDir, '.last_active'), JSON.stringify(bundle, null, 2) + '\n', 'utf8');
+
+process.exit(0);

package/plugins/xtrm-tools/hooks/beads-edit-gate.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// beads-edit-gate — Claude Code PreToolUse hook
+// Blocks file edits when this session has not claimed a beads issue via bd kv.
+// Falls back to global in_progress check when session_id is unavailable.
+// Only active in projects with a .beads/ directory.
+// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
+//
+// Installed by: xtrm install
+
+import {
+  readHookInput,
+  resolveSessionContext,
+  resolveClaimAndWorkState,
+  decideEditGate,
+  decideWorktreeBoundary,
+} from './beads-gate-core.mjs';
+import { withSafeBdContext, resolveCwd, resolveSessionId } from './beads-gate-utils.mjs';
+import { editBlockMessage, editBlockFallbackMessage } from './beads-gate-messages.mjs';
+import { logEvent } from './xtrm-logger.mjs';
+
+const input = readHookInput();
+if (!input) process.exit(0);
+
+// Worktree boundary check — independent of beads, fires first
+const _cwd = resolveCwd(input);
+const _boundary = decideWorktreeBoundary(input, _cwd);
+if (!_boundary.allow) {
+  const _wbReason = `🚫 Edit outside worktree boundary.\n  File:    ${_boundary.filePath}\n  Allowed: ${_boundary.worktreeRoot}\n\n  All edits must stay within the active worktree.`;
+  logEvent({
+    cwd: _cwd,
+    runtime: 'claude',
+    sessionId: resolveSessionId(input),
+    layer: 'gate',
+    kind: 'gate.worktree.block',
+    outcome: 'block',
+    toolName: input.tool_name,
+    message: _wbReason,
+    extra: { file: _boundary.filePath, worktree_root: _boundary.worktreeRoot },
+  });
+  process.stdout.write(JSON.stringify({ decision: 'block', reason: _wbReason }));
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
+withSafeBdContext(() => {
+  const ctx = resolveSessionContext(input);
+  if (!ctx || !ctx.isBeadsProject) process.exit(0);
+
+  const state = resolveClaimAndWorkState(ctx);
+  const decision = decideEditGate(ctx, state);
+
+  if (decision.allow) {
+    logEvent({
+      cwd: ctx.cwd,
+      runtime: 'claude',
+      sessionId: ctx.sessionId,
+      layer: 'gate',
+      kind: 'gate.edit.allow',
+      outcome: 'allow',
+      toolName: input.tool_name,
+      issueId: state?.claimId ?? null,
+      extra: { file: input.tool_input?.file_path ?? null },
+    });
+    process.exit(0);
+  }
+
+  // Block with appropriate message
+  const reason = decision.reason === 'no_claim_with_work'
+    ? editBlockMessage(decision.sessionId)
+    : editBlockFallbackMessage();
+  logEvent({
+    cwd: ctx.cwd,
+    runtime: 'claude',
+    sessionId: ctx.sessionId,
+    layer: 'gate',
+    kind: 'gate.edit.block',
+    outcome: 'block',
+    toolName: input.tool_name,
+    message: reason,
+    extra: { file: input.tool_input?.file_path ?? null, reason_code: decision.reason },
+  });
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  process.stdout.write('\n');
+  process.exit(0);
+});