xtrm-tools 0.5.25 → 0.5.26

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

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// beads-gate-core.mjs — pure decision functions for beads gate hooks
+// Import from sibling hooks using: import { ... } from './beads-gate-core.mjs';
+//
+// All functions are pure: they return decision objects, never call process.exit()
+// or write to stdout/stderr. Side effects belong in entrypoint wrappers.
+//
+// Dependencies: beads-gate-utils.mjs (adapters)
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  resolveCwd,
+  resolveSessionId,
+  isBeadsProject,
+  getSessionClaim,
+  getTotalWork,
+  getInProgress,
+  isIssueInProgress,
+  resolveWorktreeRoot,
+} from './beads-gate-utils.mjs';
+
+// ── Input parsing ────────────────────────────────────────────────────────────
+
+/**
+ * Read and parse hook input from stdin. Returns null on parse error.
+ * Entrypoints should exit 0 if this returns null (fail-open).
+ */
+export function readHookInput() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ── Session context resolution ───────────────────────────────────────────────
+
+/**
+ * Resolve session context from hook input.
+ * Returns { cwd, sessionId, isBeadsProject } or null if cwd can't be resolved.
+ */
+export function resolveSessionContext(input) {
+  const cwd = resolveCwd(input);
+  if (!cwd) return null;
+  return {
+    cwd,
+    sessionId: resolveSessionId(input),
+    isBeadsProject: isBeadsProject(cwd),
+  };
+}
+
+// ── Claim and work state resolution ──────────────────────────────────────────
+
+/**
+ * Resolve the claim and work state for a session.
+ * Returns { claimed, claimId, totalWork, inProgress } or null if bd unavailable.
+ */
+export function resolveClaimAndWorkState(ctx) {
+  if (!ctx.isBeadsProject) {
+    return { claimed: false, claimId: null, totalWork: 0, inProgress: null };
+  }
+
+  const totalWork = getTotalWork(ctx.cwd);
+  if (totalWork === null) return null; // bd unavailable
+
+  const inProgress = getInProgress(ctx.cwd);
+
+  if (ctx.sessionId) {
+    const claimId = getSessionClaim(ctx.sessionId, ctx.cwd);
+    if (claimId === null) return null; // bd kv unavailable
+    return {
+      claimed: !!claimId,
+      claimId: claimId || null,
+      claimInProgress: claimId ? isIssueInProgress(claimId, ctx.cwd) : false,
+      totalWork,
+      inProgress,
+    };
+  }
+
+  // No session_id: fallback to global in_progress check
+  return {
+    claimed: false,
+    claimId: null,
+    claimInProgress: false,
+    totalWork,
+    inProgress,
+  };
+}
+
+// ── Decision functions ───────────────────────────────────────────────────────
+
+/**
+ * Decide whether a file edit is within the active worktree boundary.
+ * If the session cwd is inside .xtrm/worktrees/<name>, block any edit whose
+ * resolved path falls outside that worktree root.
+ * Returns { allow: boolean, filePath?: string, worktreeRoot?: string }
+ */
+export function decideWorktreeBoundary(input, cwd) {
+  const filePath = input?.tool_input?.file_path;
+  if (!filePath) return { allow: true };
+
+  const worktreeRoot = resolveWorktreeRoot(cwd);
+  if (!worktreeRoot) return { allow: true }; // not in a worktree — no constraint
+
+  const abs = resolve(cwd, filePath);
+  if (abs === worktreeRoot || abs.startsWith(worktreeRoot + '/')) return { allow: true };
+
+  return { allow: false, filePath: abs, worktreeRoot };
+}
+
+/**
+ * Decide whether to allow or block an edit operation.
+ * Returns { allow: boolean, reason?: string, sessionId?: string }
+ */
+export function decideEditGate(ctx, state) {
+  // Not a beads project → allow
+  if (!ctx.isBeadsProject) {
+    return { allow: true };
+  }
+
+  // bd unavailable → fail open
+  if (state === null) {
+    return { allow: true };
+  }
+
+  // Session has an active claim → allow
+  if (state.claimed) {
+    return { allow: true };
+  }
+
+  // No trackable work → allow (clean-start state)
+  if (state.totalWork === 0) {
+    return { allow: true };
+  }
+
+  // Has session_id but no claim + has work → block
+  if (ctx.sessionId) {
+    return {
+      allow: false,
+      reason: 'no_claim_with_work',
+      sessionId: ctx.sessionId,
+    };
+  }
+
+  // Fallback: no session_id, check global in_progress
+  if (state.inProgress && state.inProgress.count > 0) {
+    return { allow: true };
+  }
+
+  // No session_id, no in_progress, but has open work → block
+  if (state.totalWork > 0) {
+    return {
+      allow: false,
+      reason: 'no_claim_fallback',
+    };
+  }
+
+  return { allow: true };
+}
+
+/**
+ * Decide whether to allow or block a git commit operation.
+ * Returns { allow: boolean, reason?: string, summary?: string, claimed?: string }
+ */
+export function decideCommitGate(ctx, state) {
+  // Not a beads project → allow
+  if (!ctx.isBeadsProject) {
+    return { allow: true };
+  }
+
+  // bd unavailable → fail open
+  if (state === null) {
+    return { allow: true };
+  }
+
+  // No active claim → allow (nothing to close)
+  if (!state.claimed) {
+    return { allow: true };
+  }
+
+  // Claimed issue is no longer in_progress → allow (closed or transferred to another agent)
+  if (!state.claimInProgress) {
+    return { allow: true };
+  }
+
+  // Session's own claimed issue is still in_progress → block (need to close first)
+  return {
+    allow: false,
+    reason: 'unclosed_claim',
+    summary: `  Claimed: ${state.claimId} (still in_progress)`,
+    claimed: state.claimId,
+  };
+}
+
+/**
+ * Decide whether to allow or block a stop operation.
+ * Returns { allow: boolean, reason?: string, summary?: string, claimed?: string }
+ */
+export function decideStopGate(ctx, state) {
+  // Not a beads project → allow
+  if (!ctx.isBeadsProject) {
+    return { allow: true };
+  }
+
+  // bd unavailable → fail open
+  if (state === null) {
+    return { allow: true };
+  }
+
+  // No active claim → allow
+  if (!state.claimed) {
+    // But check for global in_progress (no session_id fallback)
+    if (!ctx.sessionId && state.inProgress && state.inProgress.count > 0) {
+      return {
+        allow: false,
+        reason: 'global_in_progress',
+        summary: state.inProgress.summary,
+      };
+    }
+    return { allow: true };
+  }
+
+  // Claimed issue is no longer in_progress → allow (stale claim)
+  if (!state.claimInProgress) {
+    return { allow: true };
+  }
+
+  // Session's own claimed issue is still in_progress → block
+  return {
+    allow: false,
+    reason: 'unclosed_claim',
+    summary: `  Claimed: ${state.claimId} (still in_progress)`,
+    claimed: state.claimId,
+  };
+}

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

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// beads-gate-messages.mjs — centralized message templates for beads gate hooks
+// Import from sibling hooks using: import { ... } from './beads-gate-messages.mjs';
+//
+// All user-facing strings live here. Edit this file to change messaging.
+// Policy logic lives in beads-gate-core.mjs.
+
+// ── Shared workflow steps ────────────────────────────────────────────
+
+export const SESSION_CLOSE_PROTOCOL =
+  '  bd close <id> --reason="..."\n' +
+  '  xt end\n';
+
+export const COMMIT_NEXT_STEPS =
+  '  bd close <id> --reason="..."   ← closes issue + auto-commits\n' +
+  '  xt end                          ← push, PR, merge, worktree cleanup\n';
+
+// ── Edit gate messages ───────────────────────────────────────────
+
+export function editBlockMessage(_sessionId) {
+  return (
+    '🚫 No active claim — claim an issue first.\n' +
+    '  bd update <id> --claim\n'
+  );
+}
+
+export function editBlockFallbackMessage() {
+  return (
+    '🚫 No active issue — create one before editing.\n' +
+    '  bd create --title="<task>" --type=task --priority=2\n' +
+    '  bd update <id> --claim\n'
+  );
+}
+
+// ── Commit gate messages ─────────────────────────────────────────
+
+export function commitBlockMessage(summary, claimed) {
+  const issueSummary = summary ?? `  Claimed: ${claimed}`;
+  return (
+    '🚫 Close open issues before committing.\n\n' +
+    `${issueSummary}\n\n` +
+    'Next steps:\n' + COMMIT_NEXT_STEPS
+  );
+}
+
+// ── Stop gate messages ───────────────────────────────────────────
+
+export function stopBlockMessage(summary, claimed) {
+  const issueSummary = summary ?? `  Claimed: ${claimed}`;
+  return (
+    '🚫 Unresolved issues — close before stopping.\n\n' +
+    `${issueSummary}\n\n` +
+    'Next steps:\n' + SESSION_CLOSE_PROTOCOL
+  );
+}
+
+// ── Memory gate messages ─────────────────────────────────────────
+
+export function memoryPromptMessage(claimId) {
+  const claimLine = claimId ? `claim \`${claimId}\` was closed.\n` : '';
+  return (
+    `\u25cf Memory gate: ${claimLine}` +
+    'Ask: "Would this be useful in 14 days on a fresh session?"\n' +
+    '  YES → `bd remember "<insight>"`\n' +
+    '  NO  → note "nothing to persist"\n' +
+    '  Then: `touch .beads/.memory-gate-done`\n'
+  );
+}

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// beads-gate-utils.mjs — shared infrastructure for beads gate hooks
+// Import from sibling hooks using: import { ... } from './beads-gate-utils.mjs';
+// Static ES module imports resolve relative to the importing file's location,
+// not CWD, so this works regardless of the project directory.
+
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Resolve project cwd from hook input JSON. */
+export function resolveCwd(input) {
+  return input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+}
+
+/**
+ * Resolve a stable session key for beads hooks.
+ * Priority: explicit hook session id -> cwd fallback.
+ */
+export function resolveSessionId(input) {
+  return input?.session_id ?? input?.sessionId ?? resolveCwd(input);
+}
+
+/** Return true if the directory contains a .beads project. */
+export function isBeadsProject(cwd) {
+  return existsSync(join(cwd, '.beads'));
+}
+
+/**
+ * Get the claimed issue ID for a session from bd kv.
+ * Returns: issue ID string if claimed, '' if not set, null if bd kv unavailable.
+ * Note: bd kv get exits 1 for missing keys — execSync throws, so we check err.status.
+ */
+export function getSessionClaim(sessionId, cwd) {
+  try {
+    return execSync(`bd kv get "claimed:${sessionId}"`, {
+      encoding: 'utf8',
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    }).trim();
+  } catch (err) {
+    if (err.status === 1) return ''; // key not found — no claim
+    return null;                     // command failed — bd kv unavailable
+  }
+}
+
+/**
+ * Parse work counts from a bd list output string.
+ * Reads the "Total: N issues (X open, Y in progress)" summary line.
+ * Returns { open, inProgress } or null if the line is absent.
+ *
+ * This is more reliable than counting symbols or tokens: the Total line is
+ * a structured summary that doesn't depend on status-legend text or box-drawing
+ * characters, and it's present in all non-empty bd list outputs.
+ */
+function parseCounts(output) {
+  const m = output.match(/Total:\s*\d+\s+issues?\s*\((\d+)\s+open,\s*(\d+)\s+in progress\)/);
+  if (!m) return null;
+  return { open: parseInt(m[1], 10), inProgress: parseInt(m[2], 10) };
+}
+
+/**
+ * Get in_progress issues as { count, summary }.
+ * Returns null if bd is unavailable.
+ */
+export function getInProgress(cwd) {
+  try {
+    const output = execSync('bd list --status=in_progress', {
+      encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'], timeout: 8000,
+    });
+    const counts = parseCounts(output);
+    return {
+      count: counts?.inProgress ?? 0,
+      summary: output.trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return true if a specific issue ID is currently in in_progress status.
+ * Used by commit/stop gates to scope the check to the session's own claimed issue.
+ * Returns false (fail open) if bd is unavailable.
+ */
+export function isIssueInProgress(issueId, cwd) {
+  if (!issueId) return false;
+  try {
+    const output = execSync('bd list --status=in_progress', {
+      encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'], timeout: 8000,
+    });
+    return output.includes(issueId);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Count total trackable work (open + in_progress issues) using a single bd list call.
+ * Returns the count, or null if bd is unavailable.
+ */
+export function getTotalWork(cwd) {
+  try {
+    // Use default status filter (non-closed) and parse Total summary.
+    // Repeating --status is not additive in bd CLI and can collapse to one status.
+    const output = execSync('bd list', {
+      encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'], timeout: 8000,
+    });
+    const counts = parseCounts(output);
+    if (!counts) return 0; // "No issues found." — nothing to track
+    return counts.open + counts.inProgress;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the closed-this-session issue ID for a session from bd kv.
+ * Returns: issue ID string if set, '' if not set, null if bd kv unavailable.
+ */
+export function getClosedThisSession(sessionId, cwd) {
+  try {
+    return execSync(`bd kv get "closed-this-session:${sessionId}"`, {
+      encoding: 'utf8',
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    }).trim();
+  } catch (err) {
+    if (err.status === 1) return ''; // key not found
+    return null;                     // bd kv unavailable
+  }
+}
+
+/**
+ * Return true if the memory gate is pending acknowledgment for this session.
+ * Pending = closed-this-session kv is set AND .beads/.memory-gate-done marker is absent.
+ */
+export function isMemoryGatePending(sessionId, cwd) {
+  if (existsSync(join(cwd, '.beads', '.memory-gate-done'))) return false;
+  const closed = getClosedThisSession(sessionId, cwd);
+  return !!closed; // null (unavailable) is falsy → fail open
+}
+
+/**
+ * Return true if a Bash command is a memory-gate acknowledgment command.
+ * These commands are allowed even while the memory gate is pending.
+ */
+export function isMemoryAckCommand(command) {
+  return /\bbd\s+remember\b/.test(command) || /\btouch\s+\.beads\/\.memory-gate-done\b/.test(command);
+}
+
+/**
+ * If cwd is inside a .xtrm/worktrees/<name> directory, return the worktree root path.
+ * Returns null if not in a worktree.
+ */
+export function resolveWorktreeRoot(cwd) {
+  const m = cwd.match(/^(.+\/\.xtrm\/worktrees\/[^/]+)/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Clear the session claim key from bd kv. Non-fatal — best-effort cleanup.
+ */
+export function clearSessionClaim(sessionId, cwd) {
+  try {
+    execSync(`bd kv clear "claimed:${sessionId}"`, {
+      encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'], timeout: 5000,
+    });
+  } catch {
+    // non-fatal
+  }
+}
+
+/**
+ * Option C: wrap hook body with uniform fail-open error handling.
+ * Any unexpected top-level throw exits 0 (allow) rather than crashing visibly.
+ *
+ * Usage:
+ *   withSafeBdContext(() => {
+ *     // hook logic here — call process.exit() to set exit code
+ *   });
+ */
+export function withSafeBdContext(fn) {
+  try {
+    fn();
+  } catch (err) {
+    if (err instanceof TypeError || err instanceof ReferenceError || err instanceof SyntaxError) {
+      throw err;
+    }
+    process.exit(0);
+  }
+}

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

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// beads-memory-gate — Claude Code Stop hook
+// At session end, forces the agent to evaluate whether this session's work
+// produced insights worth persisting via `bd remember`.
+// Runs after beads-stop-gate (all issues already closed by that point).
+// Exit 0: allow stop  |  Exit 2: block stop (stderr shown to Claude)
+//
+// Installed by: xtrm install
+
+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, resolveSessionId, isBeadsProject, getSessionClaim, clearSessionClaim } from './beads-gate-utils.mjs';
+import { memoryPromptMessage } from './beads-gate-messages.mjs';
+import { logEvent } from './xtrm-logger.mjs';
+
+const input = readHookInput();
+if (!input) process.exit(0);
+
+const cwd = resolveCwd(input);
+if (!cwd || !isBeadsProject(cwd)) process.exit(0);
+
+const sessionId = resolveSessionId(input);
+
+// 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 */ }
+  logEvent({
+    cwd,
+    runtime: 'claude',
+    sessionId,
+    layer: 'gate',
+    kind: 'gate.memory.acked',
+    outcome: 'allow',
+  });
+  process.exit(0);
+}
+
+// Check if an issue was closed this session (set by beads-claim-sync on bd close)
+let closedIssueId = null;
+try {
+  closedIssueId = execSync(`bd kv get "closed-this-session:${sessionId}"`, {
+    encoding: 'utf8',
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    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 (!closedIssueId) process.exit(0);
+
+const memoryMessage = memoryPromptMessage();
+logEvent({
+  cwd,
+  runtime: 'claude',
+  sessionId,
+  layer: 'gate',
+  kind: 'gate.memory.triggered',
+  outcome: 'block',
+  issueId: closedIssueId,
+  message: memoryMessage,
+});
+process.stderr.write(memoryMessage);
+process.exit(2);

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

@@ -0,0 +1,53 @@
+#!/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.
+// Also blocks when xtrm session state indicates unfinished closure phases.
+// Exit 0: allow stop  |  Exit 2: block stop (stderr shown to Claude)
+
+import {
+  readHookInput,
+  resolveSessionContext,
+  resolveClaimAndWorkState,
+  decideStopGate,
+} from './beads-gate-core.mjs';
+import { withSafeBdContext } from './beads-gate-utils.mjs';
+import { stopBlockMessage } from './beads-gate-messages.mjs';
+import { logEvent } from './xtrm-logger.mjs';
+
+const input = readHookInput();
+if (!input) process.exit(0);
+
+withSafeBdContext(() => {
+  const ctx = resolveSessionContext(input);
+  if (!ctx || !ctx.isBeadsProject) process.exit(0);
+
+  const state = resolveClaimAndWorkState(ctx);
+  const decision = decideStopGate(ctx, state);
+
+  if (!decision.allow) {
+    const message = stopBlockMessage(decision.summary, decision.claimed);
+    logEvent({
+      cwd: ctx.cwd,
+      runtime: 'claude',
+      sessionId: ctx.sessionId,
+      layer: 'gate',
+      kind: 'gate.stop.block',
+      outcome: 'block',
+      issueId: decision.claimed ?? null,
+      message,
+      extra: { reason_code: decision.reason },
+    });
+    process.stderr.write(message);
+    process.exit(2);
+  }
+
+  logEvent({
+    cwd: ctx.cwd,
+    runtime: 'claude',
+    sessionId: ctx.sessionId,
+    layer: 'gate',
+    kind: 'session.end',
+    outcome: 'allow',
+  });
+  process.exit(0);
+});