@jaggerxtrm/specialists 2.1.6 → 2.1.8

package/README.md

@@ -14,13 +14,12 @@
 
 ## How it works
 
-Specialists are `.specialist.yaml` files that define an autonomous agent: its model, system prompt, task template, and permission tier. The server discovers them across three scopes:
+Specialists are `.specialist.yaml` files that define an autonomous agent: its model, system prompt, task template, and permission tier. The server discovers them across two scopes:
 
 | Scope | Location | Purpose |
 |-------|----------|---------|
 | **project** | `./specialists/` | Per-project specialists |
 | **user** | `~/.agents/specialists/` | Built-in defaults (copied on install) + your own |
-| **system** | bundled with the package | Fallback if user scope is empty |
 
 When a specialist runs, the server spawns a `pi` subprocess with the right model, tools, and system prompt injected. Output streams back in real time via cursor-based polling.
 

package/bin/install.js

@@ -138,24 +138,220 @@ const HOOK_ENTRY = {
   hooks: [{ type: 'command', command: HOOK_FILE }],
 };
 
+
+const BEADS_EDIT_GATE_FILE   = join(HOOKS_DIR, 'beads-edit-gate.mjs');
+const BEADS_COMMIT_GATE_FILE = join(HOOKS_DIR, 'beads-commit-gate.mjs');
+const BEADS_STOP_GATE_FILE   = join(HOOKS_DIR, 'beads-stop-gate.mjs');
+
+const BEADS_EDIT_GATE_SCRIPT = `#!/usr/bin/env node
+// beads-edit-gate — Claude Code PreToolUse hook
+// Blocks file edits when no beads issue is in_progress.
+// Only active in projects with a .beads/ directory.
+// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
+//
+// Installed by: npx --package=@jaggerxtrm/specialists install
+
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } 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();
+if (!existsSync(join(cwd, '.beads'))) process.exit(0);
+
+let inProgress = 0;
+try {
+  const output = execSync('bd list --status=in_progress', {
+    encoding: 'utf8',
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 8000,
+  });
+  inProgress = (output.match(/in_progress/g) ?? []).length;
+} catch {
+  process.exit(0);
+}
+
+if (inProgress === 0) {
+  process.stderr.write(
+    '\\u{1F6AB} BEADS GATE: No in_progress issue tracked.\\n' +
+    'You MUST create and claim a beads issue BEFORE editing any file:\\n\\n' +
+    '  bd create --title="<task summary>" --type=task --priority=2\\n' +
+    '  bd update <id> --status=in_progress\\n\\n' +
+    'No exceptions. Momentum is not an excuse.\\n'
+  );
+  process.exit(2);
+}
+
+process.exit(0);
+`;
+
+const BEADS_COMMIT_GATE_SCRIPT = `#!/usr/bin/env node
+// beads-commit-gate — Claude Code PreToolUse hook
+// Blocks \`git commit\` when in_progress beads issues still exist.
+// Forces: close issues first, THEN commit.
+// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
+//
+// Installed by: npx --package=@jaggerxtrm/specialists install
+
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const tool = input.tool_name ?? '';
+if (tool !== 'Bash') process.exit(0);
+
+const cmd = input.tool_input?.command ?? '';
+if (!/\\bgit\\s+commit\\b/.test(cmd)) process.exit(0);
+
+const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+if (!existsSync(join(cwd, '.beads'))) process.exit(0);
+
+let inProgress = 0;
+let summary = '';
+try {
+  const output = execSync('bd list --status=in_progress', {
+    encoding: 'utf8',
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 8000,
+  });
+  inProgress = (output.match(/in_progress/g) ?? []).length;
+  summary = output.trim();
+} catch {
+  process.exit(0);
+}
+
+if (inProgress > 0) {
+  process.stderr.write(
+    '\\u{1F6AB} BEADS GATE: Cannot commit with open in_progress issues.\\n' +
+    'Close them first, THEN commit:\\n\\n' +
+    '  bd close <id1> <id2> ...\\n' +
+    '  git add <files> && git commit -m "..."\\n\\n' +
+    \`Open issues:\\n\${summary}\\n\`
+  );
+  process.exit(2);
+}
+
+process.exit(0);
+`;
+
+const BEADS_STOP_GATE_SCRIPT = `#!/usr/bin/env node
+// beads-stop-gate — Claude Code Stop hook
+// Blocks the agent from stopping when in_progress beads issues remain.
+// Forces the session close protocol before declaring done.
+// Exit 0: allow stop  |  Exit 2: block stop (stderr shown to Claude)
+//
+// Installed by: npx --package=@jaggerxtrm/specialists install
+
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } 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();
+if (!existsSync(join(cwd, '.beads'))) process.exit(0);
+
+let inProgress = 0;
+let summary = '';
+try {
+  const output = execSync('bd list --status=in_progress', {
+    encoding: 'utf8',
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 8000,
+  });
+  inProgress = (output.match(/in_progress/g) ?? []).length;
+  summary = output.trim();
+} catch {
+  process.exit(0);
+}
+
+if (inProgress > 0) {
+  process.stderr.write(
+    '\\u{1F6AB} BEADS STOP GATE: Cannot stop with unresolved in_progress issues.\\n' +
+    'Complete the session close protocol:\\n\\n' +
+    '  bd close <id1> <id2> ...\\n' +
+    '  git add <files> && git commit -m "..."\\n' +
+    '  git push\\n\\n' +
+    \`Open issues:\\n\${summary}\\n\`
+  );
+  process.exit(2);
+}
+
+process.exit(0);
+`;
+
+const BEADS_EDIT_GATE_ENTRY = {
+  matcher: 'Edit|Write|MultiEdit|NotebookEdit|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol',
+  hooks: [{ type: 'command', command: BEADS_EDIT_GATE_FILE, timeout: 10 }],
+};
+const BEADS_COMMIT_GATE_ENTRY = {
+  matcher: 'Bash',
+  hooks: [{ type: 'command', command: BEADS_COMMIT_GATE_FILE, timeout: 10 }],
+};
+const BEADS_STOP_GATE_ENTRY = {
+  hooks: [{ type: 'command', command: BEADS_STOP_GATE_FILE, timeout: 10 }],
+};
+
 function installHook() {
   mkdirSync(HOOKS_DIR, { recursive: true });
+
+  // Write all hook files
   writeFileSync(HOOK_FILE, HOOK_SCRIPT, 'utf8');
   chmodSync(HOOK_FILE, 0o755);
+  writeFileSync(BEADS_EDIT_GATE_FILE, BEADS_EDIT_GATE_SCRIPT, 'utf8');
+  chmodSync(BEADS_EDIT_GATE_FILE, 0o755);
+  writeFileSync(BEADS_COMMIT_GATE_FILE, BEADS_COMMIT_GATE_SCRIPT, 'utf8');
+  chmodSync(BEADS_COMMIT_GATE_FILE, 0o755);
+  writeFileSync(BEADS_STOP_GATE_FILE, BEADS_STOP_GATE_SCRIPT, 'utf8');
+  chmodSync(BEADS_STOP_GATE_FILE, 0o755);
 
   let settings = {};
   if (existsSync(SETTINGS_FILE)) {
     try { settings = JSON.parse(readFileSync(SETTINGS_FILE, 'utf8')); } catch {}
   }
 
-  if (!Array.isArray(settings.hooks?.PreToolUse)) {
-    settings.hooks = settings.hooks ?? {};
-    settings.hooks.PreToolUse = [];
-  }
-
-  settings.hooks.PreToolUse = settings.hooks.PreToolUse
-    .filter(e => !e.hooks?.some(h => h.command?.includes('specialists-main-guard')));
+  settings.hooks = settings.hooks ?? {};
+
+  // PreToolUse — replace any existing specialists-managed entries
+  if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(e =>
+    !e.hooks?.some(h =>
+      h.command?.includes('specialists-main-guard') ||
+      h.command?.includes('beads-edit-gate') ||
+      h.command?.includes('beads-commit-gate')
+    )
+  );
   settings.hooks.PreToolUse.push(HOOK_ENTRY);
+  settings.hooks.PreToolUse.push(BEADS_EDIT_GATE_ENTRY);
+  settings.hooks.PreToolUse.push(BEADS_COMMIT_GATE_ENTRY);
+
+  // Stop — replace any existing beads-stop-gate entry
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
+  settings.hooks.Stop = settings.hooks.Stop.filter(e =>
+    !e.hooks?.some(h => h.command?.includes('beads-stop-gate'))
+  );
+  settings.hooks.Stop.push(BEADS_STOP_GATE_ENTRY);
 
   mkdirSync(CLAUDE_DIR, { recursive: true });
   writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + '\n', 'utf8');
@@ -229,9 +425,12 @@ section('Claude Code hooks');
 const hookExisted = existsSync(HOOK_FILE);
 installHook();
 hookExisted
-  ? ok('main-guard hook updated')
-  : ok('main-guard hook installed → ~/.claude/hooks/specialists-main-guard.mjs');
-info('Blocks Edit/Write/git commit/push on main or master branch');
+  ? ok('hooks updated (main-guard + beads gates)')
+  : ok('hooks installed → ~/.claude/hooks/');
+info('main-guard: blocks Edit/Write/git commit/push on main or master branch');
+info('beads-edit-gate: requires in_progress bead before editing files');
+info('beads-commit-gate: requires issues closed before git commit');
+info('beads-stop-gate: requires issues closed before session end');
 
 // 7. Health check
 section('Health check');

package/dist/index.js

@@ -24786,19 +24786,16 @@ class SpecialistLoader {
   cache = new Map;
   projectDir;
   userDir;
-  systemDir;
   constructor(options = {}) {
     this.projectDir = options.projectDir ?? process.cwd();
     this.userDir = options.userDir ?? join(homedir(), ".agents", "specialists");
-    this.systemDir = options.systemDir ?? join(new URL(import.meta.url).pathname, "..", "..", "specialists");
   }
   getScanDirs() {
     return [
       { path: join(this.projectDir, "specialists"), scope: "project" },
       { path: join(this.projectDir, ".claude", "specialists"), scope: "project" },
       { path: join(this.projectDir, ".agent-forge", "specialists"), scope: "project" },
-      { path: this.userDir, scope: "user" },
-      { path: this.systemDir, scope: "system" }
+      { path: this.userDir, scope: "user" }
     ].filter((d) => existsSync(d.path));
   }
   async list(category) {
@@ -24897,6 +24894,12 @@ function getProviderArgs(model) {
 }
 
 // src/pi/session.ts
+class SessionKilledError extends Error {
+  constructor() {
+    super("Session was killed");
+    this.name = "SessionKilledError";
+  }
+}
 function mapPermissionToTools(level) {
   switch (level?.toUpperCase()) {
     case "READ_ONLY":
@@ -24955,6 +24958,7 @@ class PiAgentSession {
       this._doneResolve = resolve;
       this._doneReject = reject;
     });
+    donePromise.catch(() => {});
     this._donePromise = donePromise;
     this.proc.stdout?.on("data", (chunk) => {
       this._lineBuffer += chunk.toString();
@@ -25067,10 +25071,12 @@ class PiAgentSession {
     return this._lastOutput;
   }
   kill() {
+    if (this._killed)
+      return;
     this._killed = true;
     this.proc?.kill();
     this.proc = undefined;
-    this._doneResolve?.();
+    this._doneReject?.(new SessionKilledError);
   }
 }
 
@@ -25235,6 +25241,7 @@ You have access via Bash:
         onBeadCreated?.(beadId);
     }
     let output;
+    let sessionBackend = model;
     let session;
     try {
       session = await this.sessionFactory({
@@ -25254,20 +25261,28 @@ You have access via Bash:
       onKillRegistered?.(session.kill.bind(session));
       await session.prompt(renderedTask);
       await session.waitForDone();
+      sessionBackend = session.meta.backend;
       output = await session.getLastOutput();
+      sessionBackend = session.meta.backend;
       const postScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "post") ?? [];
       for (const script of postScripts)
         runScript(script.path);
       circuitBreaker.recordSuccess(model);
     } catch (err) {
-      circuitBreaker.recordFailure(model);
-      if (beadId)
-        beadsClient?.closeBead(beadId, "ERROR", Date.now() - start, model);
+      const isCancelled = err instanceof SessionKilledError;
+      if (!isCancelled) {
+        circuitBreaker.recordFailure(model);
+      }
+      const beadStatus = isCancelled ? "CANCELLED" : "ERROR";
+      if (beadId) {
+        beadsClient?.closeBead(beadId, beadStatus, Date.now() - start, model);
+        beadsClient?.auditBead(beadId, metadata.name, model, 1);
+      }
       await hooks.emit("post_execute", invocationId, metadata.name, metadata.version, {
-        status: "ERROR",
+        status: isCancelled ? "CANCELLED" : "ERROR",
         duration_ms: Date.now() - start,
         output_valid: false,
-        error: { type: "backend_error", message: err.message }
+        error: { type: isCancelled ? "cancelled" : "backend_error", message: err.message }
       });
       throw err;
     } finally {
@@ -25288,7 +25303,7 @@ You have access via Bash:
     }
     return {
       output,
-      backend: session.meta.backend,
+      backend: sessionBackend,
       model,
       durationMs,
       specialistVersion: metadata.version,
@@ -25463,16 +25478,16 @@ async function runPipeline(steps, runner, onProgress) {
 }
 
 // src/tools/specialist/run_parallel.tool.ts
-var InvocationSchema = exports_external.object({
-  name: exports_external.string(),
-  prompt: exports_external.string(),
-  variables: exports_external.record(exports_external.string()).optional(),
-  backend_override: exports_external.string().optional()
+var InvocationSchema = objectType({
+  name: stringType(),
+  prompt: stringType(),
+  variables: recordType(stringType()).optional(),
+  backend_override: stringType().optional()
 });
-var runParallelSchema = exports_external.object({
-  specialists: exports_external.array(InvocationSchema).min(1),
-  merge_strategy: exports_external.enum(["collect", "synthesize", "vote", "pipeline"]).default("collect"),
-  timeout_ms: exports_external.number().default(120000)
+var runParallelSchema = objectType({
+  specialists: arrayType(InvocationSchema).min(1),
+  merge_strategy: enumType(["collect", "synthesize", "vote", "pipeline"]).default("collect"),
+  timeout_ms: numberType().default(120000)
 });
 function createRunParallelTool(runner) {
   return {
@@ -25502,6 +25517,7 @@ function createRunParallelTool(runner) {
         status: r.status,
         output: r.status === "fulfilled" ? r.value.output : null,
         durationMs: r.status === "fulfilled" ? r.value.durationMs : null,
+        beadId: r.status === "fulfilled" ? r.value.beadId : undefined,
         error: r.status === "rejected" ? String(r.reason?.message) : null
       }));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",