xtrm-tools 2.4.1 → 2.4.3

package/hooks/beads-compact-save.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 // Claude Code PreCompact hook — save in_progress beads issues before context is compacted.
-// Writes issue IDs to .beads/.last_active so beads-compact-restore.mjs can reinstate them.
+// 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).
-//
-// Installed by: xtrm install
 
 import { execSync } from 'node:child_process';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
+import { readSessionState } from './session-state.mjs';
 
 let input;
 try {
@@ -40,7 +40,38 @@ for (const line of output.split('\n')) {
   if (match) ids.push(match[1]);
 }
 
-if (ids.length === 0) process.exit(0);
+const sessionState = readSessionState(cwd);
+const bundle = {
+  ids,
+  sessionState: sessionState ? {
+    issueId: sessionState.issueId,
+    branch: sessionState.branch,
+    worktreePath: sessionState.worktreePath,
+    prNumber: sessionState.prNumber,
+    prUrl: sessionState.prUrl,
+    phase: sessionState.phase,
+    conflictFiles: Array.isArray(sessionState.conflictFiles) ? sessionState.conflictFiles : [],
+    startedAt: sessionState.startedAt,
+    lastChecked: sessionState.lastChecked,
+  } : null,
+  savedAt: new Date().toISOString(),
+};
+
+if (bundle.ids.length === 0 && !bundle.sessionState) process.exit(0);
+
+writeFileSync(path.join(beadsDir, '.last_active'), JSON.stringify(bundle, null, 2) + '\n', 'utf8');
+
+if (bundle.sessionState?.phase === 'waiting-merge') {
+  const pr = bundle.sessionState.prNumber != null ? `#${bundle.sessionState.prNumber}` : '(pending PR)';
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreCompact',
+        additionalSystemPrompt:
+          `PENDING: xtrm finish waiting for PR ${pr} to merge. Re-run xtrm finish to resume.`,
+      },
+    }) + '\n',
+  );
+}
 
-writeFileSync(path.join(beadsDir, '.last_active'), ids.join('\n') + '\n', 'utf8');
 process.exit(0);

package/hooks/beads-gate-messages.mjs

@@ -31,7 +31,7 @@ export const COMMIT_NEXT_STEPS =
 
 // ── Edit gate messages ───────────────────────────────────────────
 
-export function editBlockMessage(sessionId) {
+export function editBlockMessage(_sessionId) {
   return (
     '🚫 No active claim — claim an issue first.\n' +
     '  bd update <id> --claim\n'
@@ -68,6 +68,32 @@ export function stopBlockMessage(summary, claimed) {
   );
 }
 
+export function stopBlockWaitingMergeMessage(state) {
+  const pr = state.prNumber != null ? `#${state.prNumber}` : '(PR pending)';
+  const prUrl = state.prUrl ? `\nPR: ${state.prUrl}` : '';
+  return (
+    `🚫 PR ${pr} not yet merged. Run: xtrm finish\n` +
+    `${prUrl}\n` +
+    `Worktree: ${state.worktreePath}\n`
+  );
+}
+
+export function stopBlockConflictingMessage(state) {
+  const conflicts = Array.isArray(state.conflictFiles) && state.conflictFiles.length > 0
+    ? state.conflictFiles.join(', ')
+    : 'unknown files';
+  return (
+    `🚫 Merge conflicts in: ${conflicts}. Resolve, push, then: xtrm finish\n` +
+    `Worktree: ${state.worktreePath}\n`
+  );
+}
+
+export function stopWarnActiveWorktreeMessage(state) {
+  return (
+    `⚠ Session has an active worktree at ${state.worktreePath}. Consider running: xtrm finish\n`
+  );
+}
+
 // ── Memory gate messages ─────────────────────────────────────────
 
 export function memoryPromptMessage() {

package/hooks/beads-memory-gate.mjs

@@ -11,7 +11,7 @@ import { execSync } from 'node:child_process';
 import { existsSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { readHookInput } from './beads-gate-core.mjs';
-import { resolveCwd, isBeadsProject, getSessionClaim } from './beads-gate-utils.mjs';
+import { resolveCwd, isBeadsProject, getSessionClaim, clearSessionClaim } from './beads-gate-utils.mjs';
 import { memoryPromptMessage } from './beads-gate-messages.mjs';
 
 const input = readHookInput();
@@ -20,35 +20,43 @@ if (!input) process.exit(0);
 const cwd = resolveCwd(input);
 if (!cwd || !isBeadsProject(cwd)) process.exit(0);
 
+const sessionId = input.session_id ?? null;
+if (!sessionId) process.exit(0);
+
 // Agent signals evaluation complete by touching this marker, then stops again
 const marker = join(cwd, '.beads', '.memory-gate-done');
 if (existsSync(marker)) {
   try { unlinkSync(marker); } catch { /* ignore */ }
+  // Clear the claim and closed-this-session marker
+  clearSessionClaim(sessionId, cwd);
+  try {
+    execSync(`bd kv clear "closed-this-session:${sessionId}"`, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    });
+  } catch { /* ignore */ }
   process.exit(0);
 }
 
-// Only fire if this session had an active claim that is now closed
-const sessionId = input.session_id ?? null;
-if (!sessionId) process.exit(0);
-
-const claimId = getSessionClaim(sessionId, cwd);
-if (!claimId) process.exit(0); // no claim this session → no work to persist
-
-// Check if the claimed issue was closed this session
-let claimClosed = false;
+// Check if an issue was closed this session (set by beads-claim-sync on bd close)
+let closedIssueId = null;
 try {
-  const out = execSync('bd list --status=closed', {
+  closedIssueId = execSync(`bd kv get "closed-this-session:${sessionId}"`, {
     encoding: 'utf8',
     cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
-    timeout: 8000,
-  });
-  claimClosed = out.includes(claimId);
-} catch {
+    timeout: 5000,
+  }).trim();
+} catch (err) {
+  if (err.status === 1) {
+    // No closed-this-session marker → nothing to prompt about
+    process.exit(0);
+  }
   process.exit(0); // fail open
 }
 
-if (!claimClosed) process.exit(0);
+if (!closedIssueId) process.exit(0);
 
 process.stderr.write(memoryPromptMessage());
 process.exit(2);

package/hooks/beads-stop-gate.mjs

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 // beads-stop-gate — Claude Code Stop hook
 // Blocks the agent from stopping when this session has an unclosed claim in bd kv.
-// Falls back to global in_progress check when session_id is unavailable.
+// Also blocks when xtrm session state indicates unfinished closure phases.
 // Exit 0: allow stop  |  Exit 2: block stop (stderr shown to Claude)
-//
-// Installed by: xtrm install
 
 import {
   readHookInput,
@@ -13,11 +11,52 @@ import {
   decideStopGate,
 } from './beads-gate-core.mjs';
 import { withSafeBdContext } from './beads-gate-utils.mjs';
-import { stopBlockMessage } from './beads-gate-messages.mjs';
+import {
+  stopBlockMessage,
+  stopBlockWaitingMergeMessage,
+  stopBlockConflictingMessage,
+  stopWarnActiveWorktreeMessage,
+} from './beads-gate-messages.mjs';
+import { readSessionState } from './session-state.mjs';
 
 const input = readHookInput();
 if (!input) process.exit(0);
 
+function evaluateSessionState(cwd) {
+  const state = readSessionState(cwd);
+  if (!state) return { allow: true };
+
+  if (state.phase === 'cleanup-done' || state.phase === 'merged') {
+    return { allow: true, state };
+  }
+
+  if (state.phase === 'waiting-merge' || state.phase === 'pending-cleanup') {
+    return {
+      allow: false,
+      state,
+      message: stopBlockWaitingMergeMessage(state),
+    };
+  }
+
+  if (state.phase === 'conflicting') {
+    return {
+      allow: false,
+      state,
+      message: stopBlockConflictingMessage(state),
+    };
+  }
+
+  if (state.phase === 'claimed' || state.phase === 'phase1-done') {
+    return {
+      allow: true,
+      state,
+      warning: stopWarnActiveWorktreeMessage(state),
+    };
+  }
+
+  return { allow: true, state };
+}
+
 withSafeBdContext(() => {
   const ctx = resolveSessionContext(input);
   if (!ctx || !ctx.isBeadsProject) process.exit(0);
@@ -25,9 +64,20 @@ withSafeBdContext(() => {
   const state = resolveClaimAndWorkState(ctx);
   const decision = decideStopGate(ctx, state);
 
-  if (decision.allow) process.exit(0);
+  if (!decision.allow) {
+    process.stderr.write(stopBlockMessage(decision.summary, decision.claimed));
+    process.exit(2);
+  }
+
+  const sessionDecision = evaluateSessionState(ctx.cwd);
+  if (!sessionDecision.allow) {
+    process.stderr.write(sessionDecision.message);
+    process.exit(2);
+  }
+
+  if (sessionDecision.warning) {
+    process.stderr.write(sessionDecision.warning);
+  }
 
-  // Block with message
-  process.stderr.write(stopBlockMessage(decision.summary, decision.claimed));
-  process.exit(2);
+  process.exit(0);
 });

package/hooks/guard-rules.mjs

@@ -0,0 +1,117 @@
+// Canonical guard rule definitions shared across hooks, policies, and extensions.
+// Pure data module: named exports only.
+
+export const WRITE_TOOLS = [
+  'Edit',
+  'Write',
+  'MultiEdit',
+  'NotebookEdit',
+  'mcp__serena__rename_symbol',
+  'mcp__serena__replace_symbol_body',
+  'mcp__serena__insert_after_symbol',
+  'mcp__serena__insert_before_symbol',
+];
+
+export const DANGEROUS_BASH_PATTERNS = [
+  'sed\\s+-i',
+  'echo\\s+[^\\n]*>',
+  'printf\\s+[^\\n]*>',
+  'cat\\s+[^\\n]*>',
+  'tee\\b',
+  '(?:^|\\s)(?:vim|nano|vi)\\b',
+  '(?:^|\\s)mv\\b',
+  '(?:^|\\s)cp\\b',
+  '(?:^|\\s)rm\\b',
+  '(?:^|\\s)mkdir\\b',
+  '(?:^|\\s)touch\\b',
+  '(?:^|\\s)chmod\\b',
+  '(?:^|\\s)chown\\b',
+  '>>',
+  '(?:^|\\s)git\\s+add\\b',
+  '(?:^|\\s)git\\s+commit\\b',
+  '(?:^|\\s)git\\s+merge\\b',
+  '(?:^|\\s)git\\s+push\\b',
+  '(?:^|\\s)git\\s+reset\\b',
+  '(?:^|\\s)git\\s+checkout\\b',
+  '(?:^|\\s)git\\s+rebase\\b',
+  '(?:^|\\s)git\\s+stash\\b',
+  '(?:^|\\s)npm\\s+install\\b',
+  '(?:^|\\s)bun\\s+install\\b',
+  '(?:^|\\s)bun\\s+add\\b',
+  '(?:^|\\s)node\\s+(?:-e|--eval)\\b',
+  '(?:^|\\s)bun\\s+(?:-e|--eval)\\b',
+  '(?:^|\\s)python\\s+-c\\b',
+  '(?:^|\\s)perl\\s+-e\\b',
+  '(?:^|\\s)ruby\\s+-e\\b',
+];
+
+export const SAFE_BASH_PREFIXES = [
+  // Git read-only
+  'git status',
+  'git log',
+  'git diff',
+  'git show',
+  'git blame',
+  'git branch',
+  'git fetch',
+  'git remote',
+  'git config',
+  'git pull',
+  'git stash',
+  'git worktree',
+  'git checkout -b',
+  'git switch -c',
+  // Tools
+  'gh',
+  'bd',
+  'npx gitnexus',
+  // Read-only filesystem
+  'cat',
+  'ls',
+  'head',
+  'tail',
+  'pwd',
+  'which',
+  'type',
+  'env',
+  'printenv',
+  'find',
+  'grep',
+  'rg',
+  'fd',
+  'wc',
+  'sort',
+  'uniq',
+  'cut',
+  'awk',
+  'jq',
+  'yq',
+  'bat',
+  'less',
+  'more',
+  'file',
+  'stat',
+  'du',
+  'tree',
+  // Allowed writes (specific paths)
+  'touch .beads/',
+];
+
+export const NATIVE_TEAM_TOOLS = [
+  'Task',
+  'TeamCreate',
+  'TeamDelete',
+  'SendMessage',
+  'TaskCreate',
+  'TaskUpdate',
+  'TaskList',
+  'TaskGet',
+  'TaskOutput',
+  'TaskStop',
+];
+
+export const INTERACTIVE_TOOLS = [
+  'AskUserQuestion',
+  'EnterPlanMode',
+  'EnterWorktree',
+];

package/hooks/hooks.json

@@ -2,12 +2,17 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
         "hooks": [
           {
             "type": "command",
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/main-guard.mjs",
             "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-edit-gate.mjs",
+            "timeout": 5000
           }
         ]
       },
@@ -25,16 +30,6 @@
             "timeout": 5000
           }
         ]
-      },
-      {
-        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-edit-gate.mjs",
-            "timeout": 5000
-          }
-        ]
       }
     ],
     "PostToolUse": [
@@ -58,6 +53,21 @@
           }
         ]
       },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/quality-check.cjs",
+            "timeout": 30000
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/quality-check.py",
+            "timeout": 30000
+          }
+        ]
+      },
       {
         "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",
         "hooks": [
@@ -69,33 +79,33 @@
         ]
       }
     ],
-    "SessionStart": [
+    "Stop": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-compact-restore.mjs",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-stop-gate.mjs",
             "timeout": 5000
           },
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/serena-workflow-reminder.py"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-memory-gate.mjs",
+            "timeout": 8000
           }
         ]
       }
     ],
-    "Stop": [
+    "SessionStart": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-stop-gate.mjs",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-compact-restore.mjs",
             "timeout": 5000
           },
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-memory-gate.mjs",
-            "timeout": 8000
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/serena-workflow-reminder.py"
           }
         ]
       }

package/hooks/main-guard.mjs

@@ -5,7 +5,9 @@
 // Installed by: xtrm install
 
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { WRITE_TOOLS, SAFE_BASH_PREFIXES } from './guard-rules.mjs';
 
 let branch = '';
 try {
@@ -34,6 +36,7 @@ try {
 
 const tool = input.tool_name ?? '';
 const hookEventName = input.hook_event_name ?? 'PreToolUse';
+const cwd = input.cwd || process.cwd();
 
 function deny(reason) {
   process.stdout.write(JSON.stringify({
@@ -44,18 +47,23 @@ function deny(reason) {
   process.exit(0);
 }
 
-const WRITE_TOOLS = new Set([
-  'Edit',
-  'Write',
-  'MultiEdit',
-  'NotebookEdit',
-  'mcp__serena__rename_symbol',
-  'mcp__serena__replace_symbol_body',
-  'mcp__serena__insert_after_symbol',
-  'mcp__serena__insert_before_symbol',
-]);
-
-if (WRITE_TOOLS.has(tool)) {
+// Check for existing worktree/session state
+function getSessionState(cwd) {
+  const statePath = join(cwd, '.xtrm-session-state.json');
+  if (!existsSync(statePath)) return null;
+  try {
+    return JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+if (WRITE_TOOLS.includes(tool)) {
+  const state = getSessionState(cwd);
+  if (state?.worktreePath) {
+    deny(`⛔ On '${branch}' — worktree already created.\n`
+      + `  cd ${state.worktreePath}\n`);
+  }
   deny(`⛔ On '${branch}' — start on a feature branch and claim an issue.\n`
     + '  git checkout -b feature/<name>\n'
     + '  bd update <id> --claim\n');
@@ -91,17 +99,9 @@ if (tool === 'Bash') {
   // Important: do not allow generic checkout/switch forms, which include
   // mutating variants such as `git checkout -- <path>`.
   const SAFE_BASH_PATTERNS = [
-    /^git\s+(status|log|diff|branch|show|describe|fetch|remote|config)\b/,
-    /^git\s+pull\b/,
-    /^git\s+stash\b/,
-    /^git\s+worktree\b/,
-    /^git\s+checkout\s+-b\s+\S+/,
-    /^git\s+switch\s+-c\s+\S+/,
+    ...SAFE_BASH_PREFIXES.map(prefix => new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`)),
     // Allow post-merge sync to protected branch only (not arbitrary origin refs)
     ...protectedBranches.map(b => new RegExp(`^git\\s+reset\\s+--hard\\s+origin/${b}\\b`)),
-    /^gh\s+/,
-    /^bd\s+/,
-    /^touch\s+\.beads\//,
   ];
 
   if (SAFE_BASH_PATTERNS.some(p => p.test(cmd))) {