xtrm-tools 0.5.0

package/hooks/README.md

@@ -0,0 +1,75 @@
+# 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
+
+### main-guard.mjs
+
+**Purpose**: Enforces PR-only merge workflow with full git protection. Blocks direct commits and dangerous `git checkout`, `git reset`, and file writes via Bash on protected branches (`main`/`master`).
+
+**Trigger**: PreToolUse (Write|Edit|MultiEdit|Serena edit tools|Bash)
+
+**Configuration**: Installed automatically to protect the main branch from unreviewed changes.
+
+### main-guard-post-push.mjs
+
+**Purpose**: Workflow enforcement. After pushing a feature branch, reminds to open a PR, merge using `gh pr merge --squash`, and sync local via `git reset --hard origin/main`.
+
+**Trigger**: PostToolUse (Bash: git push)
+
+### 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/hooks/agent_context.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+import json
+import sys
+import os
+
+class AgentContext:
+    def __init__(self):
+        try:
+            # Read JSON from stdin once
+            self.data = json.load(sys.stdin)
+        except Exception:
+            self.data = {}
+            
+        self.tool_name = self.data.get('tool_name')
+        self.tool_input = self.data.get('tool_input', {})
+        self.event = self.data.get('hook_event_name')
+        self.prompt = self.data.get('prompt', '')
+        
+        # Determine Agent Type
+        if self.tool_name in ['run_shell_command', 'read_file', 'write_file', 'replace']:
+            self.agent_type = 'gemini'
+        elif self.tool_name in ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep']:
+            self.agent_type = 'claude'
+        else:
+            # Fallback based on env vars
+            if os.environ.get('GEMINI_PROJECT_DIR'):
+                self.agent_type = 'gemini'
+            else:
+                self.agent_type = 'claude'
+
+    def is_shell_tool(self):
+        return self.tool_name in ['Bash', 'run_shell_command']
+
+    def is_write_tool(self):
+        return self.tool_name in ['Write', 'write_file']
+
+    def is_edit_tool(self):
+        return self.tool_name in ['Edit', 'replace']
+
+    def get_command(self):
+        return self.tool_input.get('command', '')
+
+    def get_file_path(self):
+        return self.tool_input.get('file_path', '')
+
+    def block(self, reason, system_message=None):
+        """Unified block response.
+
+        Only PreToolUse hooks support permissionDecision: deny.
+        For other hooks, use continue: false to block execution.
+        """
+        output = {}
+
+        if system_message:
+            output["systemMessage"] = system_message
+
+        # Only PreToolUse hooks support permissionDecision
+        if self.event == "PreToolUse":
+            output["hookSpecificOutput"] = {
+                "hookEventName": self.event,
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason
+            }
+        else:
+            # For non-PreToolUse hooks, use continue: false to block
+            output["continue"] = False
+            output["stopReason"] = reason
+
+        print(json.dumps(output))
+        sys.exit(0)
+
+    def allow(self, system_message=None, additional_context=None):
+        """Unified allow response.
+
+        For PreToolUse hooks: outputs permissionDecision in hookSpecificOutput
+        For other hooks (UserPromptSubmit, SessionStart, PostToolUse):
+          only systemMessage and/or additionalContext are valid
+        """
+        output = {}
+
+        if system_message:
+            output["systemMessage"] = system_message
+
+        # Build hookSpecificOutput if we have PreToolUse or additionalContext
+        if self.event == "PreToolUse" or additional_context:
+            hook_output = {"hookEventName": self.event}
+
+            # Only PreToolUse supports permissionDecision
+            if self.event == "PreToolUse":
+                hook_output["permissionDecision"] = "allow"
+
+            if additional_context:
+                hook_output["additionalContext"] = additional_context
+
+            output["hookSpecificOutput"] = hook_output
+
+        # Only print output if we have something to say
+        if output:
+            print(json.dumps(output))
+
+        sys.exit(0)
+
+    def fail_open(self):
+        """Standard fail-open behavior"""
+        sys.exit(0)

package/hooks/beads-claim-sync.mjs

@@ -0,0 +1,166 @@
+#!/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 } from 'node:fs';
+import { join } from 'node:path';
+import { resolveSessionId } from './beads-gate-utils.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 autoCommit(cwd, issueId, command) {
+  if (!hasGitChanges(cwd)) {
+    return { ok: true, message: 'No changes detected — auto-commit skipped.' };
+  }
+
+  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);
+      }
+
+      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;
+
+    // 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,
+      });
+    }
+
+    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/hooks/beads-commit-gate.mjs

@@ -0,0 +1,55 @@
+#!/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, isMemoryGatePending, isMemoryAckCommand } from './beads-gate-utils.mjs';
+import { commitBlockMessage, memoryGatePendingMessage } from './beads-gate-messages.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);
+
+  // Memory gate: block all Bash except acknowledgment commands while gate pending
+  if (ctx.sessionId && isMemoryGatePending(ctx.sessionId, ctx.cwd)) {
+    if (!isMemoryAckCommand(commandUnquoted)) {
+      process.stdout.write(JSON.stringify({ decision: 'block', reason: memoryGatePendingMessage() }));
+      process.stdout.write('\n');
+      process.exit(0);
+    }
+    process.exit(0); // memory-ack command — allow
+  }
+
+  // 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) process.exit(0);
+
+  // Block with structured decision
+  const reason = commitBlockMessage(decision.summary, decision.claimed);
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  process.stdout.write('\n');
+  process.exit(0);
+});

package/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/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/hooks/beads-edit-gate.mjs

@@ -0,0 +1,45 @@
+#!/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,
+} from './beads-gate-core.mjs';
+import { withSafeBdContext, isMemoryGatePending } from './beads-gate-utils.mjs';
+import { editBlockMessage, editBlockFallbackMessage, memoryGatePendingMessage } from './beads-gate-messages.mjs';
+
+const input = readHookInput();
+if (!input) process.exit(0);
+
+withSafeBdContext(() => {
+  const ctx = resolveSessionContext(input);
+  if (!ctx || !ctx.isBeadsProject) process.exit(0);
+
+  // Memory gate takes priority: block edits while pending acknowledgment
+  if (ctx.sessionId && isMemoryGatePending(ctx.sessionId, ctx.cwd)) {
+    process.stdout.write(JSON.stringify({ decision: 'block', reason: memoryGatePendingMessage() }));
+    process.stdout.write('\n');
+    process.exit(0);
+  }
+
+  const state = resolveClaimAndWorkState(ctx);
+  const decision = decideEditGate(ctx, state);
+
+  if (decision.allow) process.exit(0);
+
+  // Block with appropriate message
+  const reason = decision.reason === 'no_claim_with_work'
+    ? editBlockMessage(decision.sessionId)
+    : editBlockFallbackMessage();
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  process.stdout.write('\n');
+  process.exit(0);
+});