xtrm-tools 2.1.29 → 2.2.0

package/cli/package.json

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

package/config/hooks.json

@@ -9,6 +9,12 @@
         "script": "serena-workflow-reminder.py"
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "script": "branch-state.mjs",
+        "timeout": 3000
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
@@ -20,10 +26,6 @@
         "script": "main-guard.mjs",
         "timeout": 5000
       },
-      {
-        "matcher": "Read|Edit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
-        "script": "serena-workflow-reminder.py"
-      },
       {
         "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
         "script": "beads-edit-gate.mjs",
@@ -37,7 +39,7 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|execute_shell_command|bash",
         "script": "beads-claim-sync.mjs",
         "timeout": 5000
       },
@@ -47,7 +49,7 @@
         "timeout": 5000
       },
       {
-        "matcher": "Read|Grep|Glob|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",
+        "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
       }

package/config/pi/extensions/beads.ts

@@ -1,43 +1,60 @@
 import type { ExtensionAPI, ToolCallEvent, ToolResultEvent } from "@mariozechner/pi-coding-agent";
 import { isToolCallEventType, isBashToolResult } from "@mariozechner/pi-coding-agent";
 import * as path from "node:path";
-import * as fs from "node:fs";
 import { SubprocessRunner, EventAdapter, Logger } from "./core/lib";
 
 const logger = new Logger({ namespace: "beads" });
 
 export default function (pi: ExtensionAPI) {
 	const getCwd = (ctx: any) => ctx.cwd || process.cwd();
-	const isBeadsProject = (cwd: string) => fs.existsSync(path.join(cwd, ".beads"));
 
-	// Pin session to PID — stable for the life of the Pi process, consistent across all extension handlers
-	const sessionId = process.pid.toString();
+	let cachedSessionId: string | null = null;
 
-	const getSessionClaim = async (cwd: string): Promise<string | null> => {
+	// Resolve a stable session ID across event types.
+	const getSessionId = (ctx: any): string => {
+		const fromManager = ctx?.sessionManager?.getSessionId?.();
+		const fromContext = ctx?.sessionId ?? ctx?.session_id;
+		const resolved = fromManager || fromContext || cachedSessionId || process.pid.toString();
+		if (resolved && !cachedSessionId) cachedSessionId = resolved;
+		return resolved;
+	};
+
+	const getSessionClaim = async (sessionId: string, cwd: string): Promise<string | null> => {
 		const result = await SubprocessRunner.run("bd", ["kv", "get", `claimed:${sessionId}`], { cwd });
 		if (result.code === 0) return result.stdout.trim();
 		return null;
 	};
 
 	const hasTrackableWork = async (cwd: string): Promise<boolean> => {
+		const result = await SubprocessRunner.run("bd", ["list"], { cwd });
+		if (result.code === 0) {
+			const counts = EventAdapter.parseBdCounts(result.stdout);
+			if (counts) return (counts.open + counts.inProgress) > 0;
+		}
+		return false;
+	};
+
+	const hasInProgressWork = async (cwd: string): Promise<boolean> => {
 		const result = await SubprocessRunner.run("bd", ["list"], { cwd });
 		if (result.code === 0 && result.stdout.includes("Total:")) {
 			const m = result.stdout.match(/Total:\s*\d+\s+issues?\s*\((\d+)\s+open,\s*(\d+)\s+in progress\)/);
-			if (m) {
-				const open = parseInt(m[1], 10);
-				const inProgress = parseInt(m[2], 10);
-				return (open + inProgress) > 0;
-			}
+			if (m) return parseInt(m[2], 10) > 0;
 		}
 		return false;
 	};
 
+	pi.on("session_start", async (_event, ctx) => {
+		cachedSessionId = ctx?.sessionManager?.getSessionId?.() ?? ctx?.sessionId ?? ctx?.session_id ?? cachedSessionId;
+		return undefined;
+	});
+
 	pi.on("tool_call", async (event, ctx) => {
 		const cwd = getCwd(ctx);
-		if (!isBeadsProject(cwd)) return undefined;
+		if (!EventAdapter.isBeadsProject(cwd)) return undefined;
+		const sessionId = getSessionId(ctx);
 
 		if (EventAdapter.isMutatingFileTool(event)) {
-			const claim = await getSessionClaim(cwd);
+			const claim = await getSessionClaim(sessionId, cwd);
 			if (!claim) {
 			    const hasWork = await hasTrackableWork(cwd);
 			    if (hasWork) {
@@ -46,7 +63,7 @@ export default function (pi: ExtensionAPI) {
 			        }
 			        return {
                         block: true,
-                        reason: `No active issue claim for this session (pid:${sessionId}).\n  bd update <id> --claim\n  bd kv set "claimed:${sessionId}" "<id>"`,
+                        reason: `No active claim for session ${sessionId}.\n  bd update <id> --claim\n`,
                     };
                 }
             }
@@ -55,12 +72,15 @@ export default function (pi: ExtensionAPI) {
 		if (isToolCallEventType("bash", event)) {
 			const command = event.input.command;
 			if (command && /\bgit\s+commit\b/.test(command)) {
-                const claim = await getSessionClaim(cwd);
+				const claim = await getSessionClaim(sessionId, cwd);
 				if (claim) {
-					return {
-                        block: true,
-                        reason: `Resolve open claim [${claim}] before committing.`,
-                    };
+					const inProgress = await hasInProgressWork(cwd);
+					if (inProgress) {
+						return {
+							block: true,
+							reason: `Active claim [${claim}] — close it first.\n  bd close ${claim}\n  git push -u origin <feature-branch>\n  gh pr create --fill && gh pr merge --squash\n`,
+						};
+					}
 				}
 			}
 		}
@@ -71,6 +91,7 @@ export default function (pi: ExtensionAPI) {
 	pi.on("tool_result", async (event, ctx) => {
 		if (isBashToolResult(event)) {
 			const command = event.input.command;
+			const sessionId = getSessionId(ctx);
 
 			// Auto-claim on bd update --claim regardless of exit code.
 			// bd returns exit 1 with "already in_progress" when status unchanged — still a valid claim intent.
@@ -80,7 +101,7 @@ export default function (pi: ExtensionAPI) {
 					const issueId = issueMatch[1];
 					const cwd = getCwd(ctx);
 					await SubprocessRunner.run("bd", ["kv", "set", `claimed:${sessionId}`, issueId], { cwd });
-					const claimNotice = `\n\n✅ **Beads**: Session \`pid:${sessionId}\` claimed issue \`${issueId}\`. File edits are now unblocked.`;
+					const claimNotice = `\n\n✅ **Beads**: Session \`${sessionId}\` claimed issue \`${issueId}\`. File edits are now unblocked.`;
 					return { content: [...event.content, { type: "text", text: claimNotice }] };
 				}
 			}
@@ -93,4 +114,25 @@ export default function (pi: ExtensionAPI) {
 		}
 		return undefined;
 	});
+
+	// Dual safety net: notify about unclosed claims when session ends
+	const notifySessionEnd = async (ctx: any) => {
+		const cwd = getCwd(ctx);
+		if (!EventAdapter.isBeadsProject(cwd)) return;
+		const sessionId = getSessionId(ctx);
+		const claim = await getSessionClaim(sessionId, cwd);
+		if (claim && ctx.hasUI) {
+			ctx.ui.notify(`Beads: Session ending with active claim [${claim}]`, "warning");
+		}
+	};
+
+	pi.on("agent_end", async (_event, ctx) => {
+		await notifySessionEnd(ctx);
+		return undefined;
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		await notifySessionEnd(ctx);
+		return undefined;
+	});
 }

package/config/pi/extensions/core/adapter.ts

@@ -1,3 +1,6 @@
+import * as fs from "node:fs";
+import * as nodePath from "node:path";
+
 import type { ExtensionAPI, ToolCallEvent } from "@mariozechner/pi-coding-agent";
 
 export class EventAdapter {
@@ -42,4 +45,20 @@ export class EventAdapter {
 	static formatBlockReason(prefix: string, details: string): string {
 		return `${prefix}: ${details}`;
 	}
+	/**
+	 * Returns true if the given directory is a beads project (has a .beads directory).
+	 */
+	static isBeadsProject(cwd: string): boolean {
+		return fs.existsSync(nodePath.join(cwd, ".beads"));
+	}
+
+	/**
+	 * Parses the summary line from `bd list` output.
+	 * Returns { open, inProgress } or null if the line is absent.
+	 */
+	static parseBdCounts(output: string): { open: number; inProgress: number } | null {
+		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) };
+	}
 }

package/config/pi/extensions/custom-footer.ts

@@ -7,9 +7,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { truncateToWidth } from "@mariozechner/pi-tui";
 
-import * as path from "node:path";
-import * as fs from "node:fs";
-import { SubprocessRunner } from "./core/lib";
+import { SubprocessRunner, EventAdapter } from "./core/lib";
 
 export default function (pi: ExtensionAPI) {
 	interface BeadState {
@@ -26,10 +24,19 @@ export default function (pi: ExtensionAPI) {
 		blocked: "●",
 		closed: "✓",
 	};
+	// Chip background colours (raw ANSI — theme has no bg() API)
+	const CHIP_BG_NEUTRAL  = "\x1b[48;5;238m"; // dark gray
+	const CHIP_BG_ACTIVE   = "\x1b[48;5;39m";  // blue
+	const CHIP_BG_BLOCKED  = "\x1b[48;5;88m";  // red
+	const CHIP_FG          = "\x1b[38;5;15m";  // white
+	const CHIP_RESET       = "\x1b[0m";
+	const chip = (text: string, bg = CHIP_BG_NEUTRAL): string =>
+		`${bg}${CHIP_FG} ${text} ${CHIP_RESET}`;
+
 	const STATUS_BG: Record<string, string> = {
-		open: "\x1b[48;5;238m",
-		in_progress: "\x1b[48;5;39m",
-		blocked: "\x1b[48;5;88m",
+		open: CHIP_BG_NEUTRAL,
+		in_progress: CHIP_BG_ACTIVE,
+		blocked: CHIP_BG_BLOCKED,
 	};
 
 	let capturedCtx: any = null;
@@ -40,13 +47,12 @@ export default function (pi: ExtensionAPI) {
 	const CACHE_TTL = 5000;
 
 	const getCwd = () => capturedCtx?.cwd || process.cwd();
-	const isBeadsProject = (cwd: string) => fs.existsSync(path.join(cwd, ".beads"));
 	const getShortId = (id: string) => id.split("-").pop() ?? id;
 
 	const refreshBeadState = async () => {
 		if (refreshing || Date.now() - beadState.lastFetch < CACHE_TTL) return;
 		const cwd = getCwd();
-		if (!isBeadsProject(cwd)) return;
+		if (!EventAdapter.isBeadsProject(cwd)) return;
 		if (!sessionId) return;
 		refreshing = true;
 		try {
@@ -84,19 +90,19 @@ export default function (pi: ExtensionAPI) {
 		const { claimId, shortId, status, openCount } = beadState;
 		if (claimId && shortId && status) {
 			const icon = STATUS_ICONS[status] ?? "?";
-			const bg = STATUS_BG[status] ?? "\x1b[48;5;238m";
-			return `${bg}\x1b[38;5;15m bd:${shortId}${icon} \x1b[0m`;
+			const bg = STATUS_BG[status] ?? CHIP_BG_NEUTRAL;
+			return chip(`bd:${shortId}${icon}`, bg);
 		}
 		if (openCount > 0) {
-			return `\x1b[48;5;238m\x1b[38;5;15m bd:${openCount}${STATUS_ICONS.open} \x1b[0m`;
+			return chip(`bd:${openCount}${STATUS_ICONS.open}`);
 		}
 		return "";
 	};
 
 	pi.on("session_start", async (_event, ctx) => {
 		capturedCtx = ctx;
-		// Get session ID from sessionManager (UUID, consistent with hooks)
-		sessionId = ctx.sessionManager?.getSessionId?.() ?? process.pid.toString();
+		// Get session ID from sessionManager/context (prefer UUID, consistent with hooks)
+		sessionId = ctx.sessionManager?.getSessionId?.() ?? ctx.sessionId ?? ctx.session_id ?? process.pid.toString();
 
 		ctx.ui.setFooter((tui, theme, footerData) => {
 			requestRender = () => tui.requestRender();
@@ -108,7 +114,8 @@ export default function (pi: ExtensionAPI) {
 				render(width: number): string[] {
 					refreshBeadState().catch(() => {});
 
-					const brand = "\x1b[1m" + theme.fg("accent", "XTRM") + "\x1b[22m";
+					const BOLD = "\x1b[1m", BOLD_OFF = "\x1b[22m";
+					const brand = `${BOLD}${theme.fg("accent", "XTRM")}${BOLD_OFF}`;
 
 					const usage = ctx.getContextUsage();
 					const pct = usage?.percent ?? 0;
@@ -123,7 +130,7 @@ export default function (pi: ExtensionAPI) {
 					const branchStr = branch ? theme.fg("accent", `⎇ ${branch}`) : "";
 
 					const modelId = ctx.model?.id || "no-model";
-					const modelChip = `\x1b[48;5;238m\x1b[38;5;15m ${modelId} \x1b[0m`;
+					const modelChip = chip(modelId);
 
 					const sep = theme.fg("dim", " | ");
 

package/config/pi/extensions/main-guard.ts

@@ -54,7 +54,7 @@ export default function (pi: ExtensionAPI) {
 		if (branch && protectedBranches.includes(branch)) {
 			// A. Mutating File Tools on Main
 			if (EventAdapter.isMutatingFileTool(event)) {
-				const reason = `On protected branch '${branch}'. Checkout a feature branch first: \`git checkout -b feature/<name>\``;
+				const reason = `On protected branch '${branch}' — start on a feature branch and claim an issue.\n  git checkout -b feature/<name>\n  bd update <id> --claim\n`;
 				if (ctx.hasUI) {
 					ctx.ui.notify(`Main-Guard: Blocked edit on ${branch}`, "error");
 				}
@@ -97,7 +97,7 @@ export default function (pi: ExtensionAPI) {
 
 				// Specific blocks
 				if (/\bgit\s+commit\b/.test(cmd)) {
-					return { block: true, reason: `No commits on '${branch}' — use a feature branch.` };
+					return { block: true, reason: `No commits on '${branch}' — use a feature branch.\n  git checkout -b feature/<name>\n  bd update <id> --claim\n` };
 				}
 
 				if (/\bgit\s+push\b/.test(cmd)) {
@@ -113,7 +113,7 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				// Default deny
-				const reason = `Bash restricted on '${branch}'. Allowed: git status/log/diff/pull/stash, gh, bd.\n  Exit: git checkout -b feature/<name>`;
+				const reason = `Bash restricted on '${branch}'. Allowed: git status/log/diff/pull/stash, gh, bd.\n  Exit: git checkout -b feature/<name>\n  Then: bd update <id> --claim\n  Override: MAIN_GUARD_ALLOW_BASH=1 <cmd>\n`;
 				if (ctx.hasUI) {
 					ctx.ui.notify("Main-Guard: Command blocked", "error");
 				}

package/config/pi/extensions/service-skills.ts

@@ -26,38 +26,6 @@ export default function (pi: ExtensionAPI) {
 		return undefined;
 	});
 
-	// 2. Territory Activation
-	pi.on("tool_call", async (event, ctx) => {
-		const cwd = getCwd(ctx);
-		const activatorPath = path.join(cwd, ".claude", "skills", "using-service-skills", "scripts", "skill_activator.py");
-		if (!fs.existsSync(activatorPath)) return undefined;
-
-		const hookInput = JSON.stringify({
-			tool_name: event.toolName === "bash" ? "Bash" : event.toolName,
-			tool_input: event.input,
-			cwd: cwd
-		});
-
-		const result = await SubprocessRunner.run("python3", [activatorPath], {
-			cwd,
-			input: hookInput,
-			env: { ...process.env, CLAUDE_PROJECT_DIR: cwd },
-			timeoutMs: 5000
-		});
-
-		if (result.code === 0 && result.stdout.trim()) {
-			try {
-				const parsed = JSON.parse(result.stdout.trim());
-				const context = parsed.hookSpecificOutput?.additionalContext;
-				if (context && ctx.hasUI) {
-					ctx.ui.notify(context, "info");
-				}
-			} catch (e) {
-				logger.error("Failed to parse skill_activator output", e);
-			}
-		}
-		return undefined;
-	});
 
 	// 3. Drift Detection
 	pi.on("tool_result", async (event, ctx) => {

package/config/pi/extensions/xtrm-loader.ts

@@ -40,7 +40,7 @@ export default function (pi: ExtensionAPI) {
 
 		for (const p of roadmapPaths) {
 			if (fs.existsSync(p)) {
-				const content = fs.readFileSync(p, "utf8");
+				const content = await fs.promises.readFile(p, "utf8");
 				contextParts.push(`## Project Roadmap & Architecture (${path.relative(cwd, p)})\n\n${content}`);
 				break; // Only load the first one found
 			}
@@ -51,10 +51,10 @@ export default function (pi: ExtensionAPI) {
 		if (fs.existsSync(rulesDir)) {
 			const ruleFiles = findMarkdownFiles(rulesDir);
 			if (ruleFiles.length > 0) {
-				const rulesContent = ruleFiles.map(f => {
-					const content = fs.readFileSync(path.join(rulesDir, f), "utf8");
+				const rulesContent = (await Promise.all(ruleFiles.map(async f => {
+					const content = await fs.promises.readFile(path.join(rulesDir, f), "utf8");
 					return `### Rule: ${f}\n${content}`;
-				}).join("\n\n");
+				}))).join("\n\n");
 				contextParts.push(`## Project Rules\n\n${rulesContent}`);
 			}
 		}

package/hooks/beads-claim-sync.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 // beads-claim-sync — PostToolUse hook
-// Auto-sets bd kv claim when bd update --claim is detected.
-// Uses session_id from hook input (UUID, matches Pi's sessionManager.getSessionId())
+// Auto-sets kv claim on bd update --claim; auto-clears on bd close.
 
 import { spawnSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
@@ -19,44 +18,79 @@ 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 main() {
   const input = readInput();
   if (!input || input.hook_event_name !== 'PostToolUse') process.exit(0);
-  if (input.tool_name !== 'Bash') 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 || '';
-  if (!/\bbd\s+update\b/.test(command) || !/--claim\b/.test(command)) {
+  const sessionId = input.session_id ?? input.sessionId;
+
+  if (!sessionId) {
+    process.stderr.write('Beads claim sync: no session_id in hook input\n');
     process.exit(0);
   }
 
-  // Extract issue ID from command
-  const match = command.match(/\bbd\s+update\s+(\S+)/);
-  if (!match) process.exit(0);
+  // 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,
+      });
 
-  const issueId = match[1];
-  // Use session_id from hook input (UUID from Pi/Claude Code)
-  const sessionId = input.session_id;
+      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);
+      }
 
-  if (!sessionId) {
-    process.stderr.write('Beads claim sync: no session_id in hook input\n');
-    process.exit(0);
+      process.stdout.write(JSON.stringify({
+        additionalContext: `\n✅ **Beads**: Session \`${sessionId}\` claimed issue \`${issueId}\`.`,
+      }));
+      process.stdout.write('\n');
+      process.exit(0);
+    }
   }
 
-  try {
-    spawnSync('bd', ['kv', 'set', `claimed:${sessionId}`, issueId], {
+  // Auto-clear: bd close <id> — remove the kv claim so commit gate unblocks
+  if (/\bbd\s+close\b/.test(command) && commandSucceeded(input)) {
+    const result = spawnSync('bd', ['kv', 'clear', `claimed:${sessionId}`], {
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
       timeout: 5000,
     });
-    process.stdout.write(JSON.stringify({
-      additionalContext: `\n✅ **Beads**: Session \`${sessionId}\` claimed issue \`${issueId}\`.`,
-    }));
-    process.stdout.write('\n');
-  } catch (err) {
-    process.stderr.write(`Beads claim sync warning: ${err.message}\n`);
+
+    if (result.status === 0) {
+      process.stdout.write(JSON.stringify({
+        additionalContext: `\n🔓 **Beads**: Session claim cleared. Ready to commit.`,
+      }));
+      process.stdout.write('\n');
+    }
+    process.exit(0);
   }
 
   process.exit(0);

package/hooks/beads-commit-gate.mjs

@@ -32,7 +32,9 @@ withSafeBdContext(() => {
 
   if (decision.allow) process.exit(0);
 
-  // Block with message
-  process.stderr.write(commitBlockMessage(decision.summary, decision.claimed));
-  process.exit(2);
+  // 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-edit-gate.mjs

@@ -29,10 +29,10 @@ withSafeBdContext(() => {
   if (decision.allow) process.exit(0);
 
   // Block with appropriate message
-  if (decision.reason === 'no_claim_with_work') {
-    process.stderr.write(editBlockMessage(decision.sessionId));
-  } else {
-    process.stderr.write(editBlockFallbackMessage());
-  }
-  process.exit(2);
+  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);
 });

package/hooks/beads-gate-messages.mjs

@@ -5,32 +5,36 @@
 // All user-facing strings live here. Edit this file to change messaging.
 // Policy logic lives in beads-gate-core.mjs.
 
-// ── Shared workflow steps ────────────────────────────────────────────────────
+// ── Shared workflow steps ────────────────────────────────────────────
 
 export const WORKFLOW_STEPS =
   '  1. git checkout -b feature/<name>\n' +
-  '  2. bd create + bd update in_progress\n' +
+  '  2. bd update <id> --claim\n' +
   '  3. Edit / write code\n' +
-  '  4. bd close <id> && git add && git commit\n' +
-  '  5. git push -u origin feature/<name>\n' +
-  '  6. gh pr create --fill && gh pr merge --squash\n' +
-  '  7. git checkout master && git reset --hard origin/master\n';;
+  '  4. bd close <id>\n' +
+  '  5. git add -p && git commit -m "<message>"\n' +
+  '  6. git push -u origin feature/<name>\n' +
+  '  7. gh pr create --fill && gh pr merge --squash\n' +
+  '  8. git checkout master && git reset --hard origin/master\n';
 
 export const SESSION_CLOSE_PROTOCOL =
-  '  bd close <id> → commit → push → gh pr create --fill → gh pr merge --squash\n';;
+  '  bd close <id>\n' +
+  '  git add -p && git commit -m "<message>"\n' +
+  '  git push -u origin <feature-branch>\n' +
+  '  gh pr create --fill && gh pr merge --squash\n';
 
 export const COMMIT_NEXT_STEPS =
-  '  bd close <id> && git add && git commit\n' +
+  '  bd close <id>\n' +
+  '  git add -p && git commit -m "<message>"\n' +
   '  git push -u origin <feature-branch>\n' +
-  '  gh pr create --fill && gh pr merge --squash\n';;
+  '  gh pr create --fill && gh pr merge --squash\n';
 
-// ── Edit gate messages ───────────────────────────────────────────────────────
+// ── Edit gate messages ───────────────────────────────────────────
 
 export function editBlockMessage(sessionId) {
   return (
     '🚫 No active claim — claim an issue first.\n' +
-    '  bd update <id> --status=in_progress\n' +
-    `  bd kv set "claimed:${sessionId}" "<id>"\n`
+    '  bd update <id> --claim\n'
   );
 }
 
@@ -38,11 +42,11 @@ export function editBlockFallbackMessage() {
   return (
     '🚫 No active issue — create one before editing.\n' +
     '  bd create --title="<task>" --type=task --priority=2\n' +
-    '  bd update <id> --status=in_progress\n'
+    '  bd update <id> --claim\n'
   );
 }
 
-// ── Commit gate messages ─────────────────────────────────────────────────────
+// ── Commit gate messages ─────────────────────────────────────────
 
 export function commitBlockMessage(summary, claimed) {
   const issueSummary = summary ?? `  Claimed: ${claimed}`;
@@ -53,18 +57,18 @@ export function commitBlockMessage(summary, claimed) {
   );
 }
 
-// ── Stop gate messages ───────────────────────────────────────────────────────
+// ── Stop gate messages ───────────────────────────────────────────
 
 export function stopBlockMessage(summary, claimed) {
   const issueSummary = summary ?? `  Claimed: ${claimed}`;
   return (
     '🚫 Unresolved issues — close before stopping.\n\n' +
     `${issueSummary}\n\n` +
-    SESSION_CLOSE_PROTOCOL
+    'Next steps:\n' + SESSION_CLOSE_PROTOCOL
   );
 }
 
-// ── Memory gate messages ─────────────────────────────────────────────────────
+// ── Memory gate messages ─────────────────────────────────────────
 
 export function memoryPromptMessage() {
   return (