swarmdo 1.58.15 → 1.58.23

package/.claude/agents/base-template-generator.md

@@ -1,6 +1,6 @@
 ---
 name: base-template-generator
-description: Use this agent when you need to create foundational templates, boilerplate code, or starter configurations for new projects, components, or features. This agent excels at generating clean, well-structured base templates that follow best practices and can be easily customized. Examples: <example>Context: User needs to start a new React component and wants a solid foundation. user: 'I need to create a new user profile component' assistant: 'I'll use the base-template-generator agent to create a comprehensive React component template with proper structure, TypeScript definitions, and styling setup.' <commentary>Since the user needs a foundational template for a new component, use the base-template-generator agent to create a well-structured starting point.</commentary></example> <example>Context: User is setting up a new API endpoint and needs a template. user: 'Can you help me set up a new REST API endpoint for user management?' assistant: 'I'll use the base-template-generator agent to create a complete API endpoint template with proper error handling, validation, and documentation structure.' <commentary>The user needs a foundational template for an API endpoint, so use the base-template-generator agent to provide a comprehensive starting point.</commentary></example>
+description: "Use this agent when you need to create foundational templates, boilerplate code, or starter configurations for new projects, components, or features. This agent excels at generating clean, well-structured base templates that follow best practices and can be easily customized. Examples: <example>Context: User needs to start a new React component and wants a solid foundation. user: 'I need to create a new user profile component' assistant: 'I'll use the base-template-generator agent to create a comprehensive React component template with proper structure, TypeScript definitions, and styling setup.' <commentary>Since the user needs a foundational template for a new component, use the base-template-generator agent to create a well-structured starting point.</commentary></example> <example>Context: User is setting up a new API endpoint and needs a template. user: 'Can you help me set up a new REST API endpoint for user management?' assistant: 'I'll use the base-template-generator agent to create a complete API endpoint template with proper error handling, validation, and documentation structure.' <commentary>The user needs a foundational template for an API endpoint, so use the base-template-generator agent to provide a comprehensive starting point.</commentary></example>"
 ---
 
 You are a Base Template Generator, an expert architect specializing in creating clean, well-structured foundational templates and boilerplate code. Your expertise lies in establishing solid starting points that follow industry best practices, maintain consistency, and provide clear extension paths.

package/.claude/agents/goal/code-goal-planner.md

@@ -1,6 +1,6 @@
 ---
 name: code-goal-planner
-description: Code-centric Goal-Oriented Action Planning specialist that creates intelligent plans for software development objectives. Excels at breaking down complex coding tasks into achievable milestones with clear success criteria. Examples: <example>Context: User needs to implement a new authentication system. user: 'I need to add OAuth2 authentication to our API' assistant: 'I'll use the code-goal-planner agent to create a comprehensive implementation plan with milestones for OAuth2 integration, including provider setup, token management, and security considerations.' <commentary>Since this is a complex feature implementation, the code-goal-planner will break it down into testable milestones.</commentary></example> <example>Context: User wants to improve application performance. user: 'Our app is slow, we need to optimize database queries' assistant: 'I'll use the code-goal-planner agent to develop a performance optimization plan with measurable targets for query optimization, including profiling, indexing strategies, and caching implementation.' <commentary>Performance optimization requires systematic planning with clear metrics, perfect for code-goal-planner.</commentary></example>
+description: "Code-centric Goal-Oriented Action Planning specialist that creates intelligent plans for software development objectives. Excels at breaking down complex coding tasks into achievable milestones with clear success criteria. Examples: <example>Context: User needs to implement a new authentication system. user: 'I need to add OAuth2 authentication to our API' assistant: 'I'll use the code-goal-planner agent to create a comprehensive implementation plan with milestones for OAuth2 integration, including provider setup, token management, and security considerations.' <commentary>Since this is a complex feature implementation, the code-goal-planner will break it down into testable milestones.</commentary></example> <example>Context: User wants to improve application performance. user: 'Our app is slow, we need to optimize database queries' assistant: 'I'll use the code-goal-planner agent to develop a performance optimization plan with measurable targets for query optimization, including profiling, indexing strategies, and caching implementation.' <commentary>Performance optimization requires systematic planning with clear metrics, perfect for code-goal-planner.</commentary></example>"
 ---
 
 You are a Code-Centric Goal-Oriented Action Planning (GOAP) specialist integrated with SPARC methodology, focused exclusively on software development objectives. You excel at transforming vague development requirements into concrete, achievable coding milestones using the systematic SPARC approach (Specification, Pseudocode, Architecture, Refinement, Completion) with clear success criteria and measurable outcomes.

package/.claude/helpers/agent-bridge-hook.cjs

@@ -0,0 +1,174 @@
+/**
+ * agent-bridge-hook.cjs — bind real Claude Code subagents into Swarmdo's
+ * canonical agent registry, automatically.
+ *
+ * #108. `src/agent-bridge/bridge.ts` was written to solve "a session can run
+ * four Claude Code agents while `swarmdo agent list` stays empty", and is pure
+ * by design because "All fs / MCP / spawning lives in the command + hook
+ * layers". The command layer got built (`swarmdo agent bridge register`); the
+ * hook layer never did. So nothing ever registered a Task/Agent-tool subagent,
+ * `.swarmdo/agents/store.json` stayed `{"agents":{}}`, and the statusline's
+ * `🐝 Swarms N   🤖 Agents M` sat at 0/0 forever. This file is that missing
+ * hook layer.
+ *
+ * Why shell out to the CLI instead of writing the store here: registering is
+ * not just a store write — `agent_bridge_register` also auto-forms a swarm from
+ * config and enrolls the agent (agent-tools.ts:462), which is what makes the
+ * Swarms counter move too. bridge.ts's own rule is to go through the canonical
+ * registerAgent path — "NO parallel store". Reimplementing that in CJS would
+ * fork the registry. The CLI costs ~850ms to boot (it loads ONNX), far too slow
+ * to block every subagent spawn, so calls are fired detached and unref'd: the
+ * hook returns immediately and the registry lands ~1s later. The statusline
+ * polls every 5s, so eventual consistency is invisible here.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+/**
+ * Mirror of src/agent-bridge/bridge.ts `bridgeAgentId` — kept in sync by hand,
+ * because this hook is standalone CommonJS and cannot import the ESM engine
+ * (the same constraint router.cjs already works under for classifyPrompt).
+ * __tests__/agent-bridge-hook.test.ts asserts the two implementations agree.
+ *
+ * Deterministic, so SubagentStart and SubagentStop derive the SAME id from the
+ * same agent_id and the stop reliably terminates the record the start created.
+ */
+function bridgeAgentId(d) {
+  const sess = d.sessionId
+    ? d.sessionId.replace(/[^A-Za-z0-9]/g, '').slice(0, 8) || 'nosess'
+    : 'nosess';
+  const safe = String(d.name || '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'agent';
+  return `cc-${sess}-${safe}`;
+}
+
+/**
+ * Locate an installed CLI bin. Mirror of statusline.cjs resolveCliBin() — same
+ * candidate order, same reason (#2337): never `npx @latest` from a hook.
+ * Returns null when nothing is installed, in which case we no-op rather than
+ * pay a registry round-trip on every subagent spawn.
+ */
+function resolveCliBin(cwd) {
+  try {
+    const home = os.homedir();
+    const base = cwd || process.cwd();
+    const candidates = [
+      path.join(home, '.claude', 'plugins', 'marketplaces', 'swarmdo', 'bin', 'cli.js'),
+      path.join(base, 'node_modules', '@swarmdo', 'cli', 'bin', 'cli.js'),
+      path.join(base, 'node_modules', 'swarmdo', 'bin', 'cli.js'),
+      path.join(base, 'v3', '@swarmdo', 'cli', 'bin', 'cli.js'),
+    ];
+    try {
+      const binDir = path.dirname(process.execPath);
+      const globalModuleDirs = [
+        path.join(binDir, '..', 'lib', 'node_modules'),
+        path.join(binDir, 'node_modules'),
+        '/opt/homebrew/lib/node_modules',
+        '/usr/local/lib/node_modules',
+      ];
+      for (const prefix of [process.env.npm_config_prefix, process.env.PREFIX, path.join(home, '.npm-global')]) {
+        if (prefix) globalModuleDirs.push(path.join(prefix, 'lib', 'node_modules'));
+      }
+      for (const gm of globalModuleDirs) {
+        candidates.push(
+          path.join(gm, 'swarmdo', 'bin', 'cli.js'),
+          path.join(gm, '@swarmdo', 'cli', 'bin', 'cli.js'),
+        );
+      }
+    } catch { /* ignore */ }
+    for (const p of candidates) {
+      if (fs.existsSync(p)) return p;
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+/**
+ * Is this hook payload a real subagent event we should act on? `agent_id` is
+ * present ONLY when the hook fires for a subagent, so it doubles as the guard
+ * against main-thread invocations. Pure.
+ */
+function isSubagentEvent(hookInput) {
+  const id = hookInput && (hookInput.agent_id || hookInput.agentId);
+  return typeof id === 'string' && id.length > 0;
+}
+
+/**
+ * Build the `agent bridge register` argv for a SubagentStart payload, or null
+ * when the payload is not a subagent event. Pure — the spawn happens in
+ * register(). Registering is idempotent on name+session, so a duplicate
+ * SubagentStart updates the bound record rather than forking a second one.
+ */
+function buildRegisterArgs(hookInput) {
+  if (!isSubagentEvent(hookInput)) return null;
+  const agentId = hookInput.agent_id || hookInput.agentId;
+  const sessionId = hookInput.session_id || hookInput.sessionId || '';
+  const agentType = hookInput.agent_type || hookInput.agentType || 'general-purpose';
+  const args = ['agent', 'bridge', 'register', '-n', agentId, '-t', agentType];
+  if (sessionId) args.push('-s', sessionId);
+  return args;
+}
+
+/**
+ * Build the `agent stop` argv for a SubagentStop payload, or null when the
+ * payload is not a subagent event. `agent stop` sets status='terminated'
+ * (agent-tools.ts:721), which is precisely what computeSwarmStatus filters on,
+ * so the Agents count decrements when a subagent finishes. `-f` because a hook
+ * has no TTY and must not hit the interactive confirm. Pure.
+ */
+function buildTerminateArgs(hookInput) {
+  if (!isSubagentEvent(hookInput)) return null;
+  const id = bridgeAgentId({
+    name: hookInput.agent_id || hookInput.agentId,
+    sessionId: hookInput.session_id || hookInput.sessionId,
+  });
+  return ['agent', 'stop', id, '-f'];
+}
+
+/**
+ * Fire a CLI subcommand and forget it. Detached + unref'd + stdio ignored so
+ * the hook process can exit immediately without waiting on the CLI's ~850ms
+ * boot, and without the child dying alongside it.
+ */
+function spawnDetached(args, cwd) {
+  const cliBin = resolveCliBin(cwd);
+  if (!cliBin) return false;
+  try {
+    const child = spawn(process.execPath, [cliBin, ...args], {
+      cwd: cwd || process.cwd(),
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** SubagentStart → bind the subagent (and auto-form its swarm). */
+function register(hookInput, cwd) {
+  const args = buildRegisterArgs(hookInput);
+  if (!args) return false;
+  return spawnDetached(args, cwd || (hookInput && hookInput.cwd));
+}
+
+/** SubagentStop → mark the bound record terminated. */
+function terminate(hookInput, cwd) {
+  const args = buildTerminateArgs(hookInput);
+  if (!args) return false;
+  return spawnDetached(args, cwd || (hookInput && hookInput.cwd));
+}
+
+module.exports = {
+  bridgeAgentId,
+  resolveCliBin,
+  isSubagentEvent,
+  buildRegisterArgs,
+  buildTerminateArgs,
+  spawnDetached,
+  register,
+  terminate,
+};

package/.claude/helpers/hook-handler.cjs

@@ -34,6 +34,7 @@ const router = safeRequire(path.join(helpersDir, 'router.cjs'));
 const session = safeRequire(path.join(helpersDir, 'session.cjs'));
 const memory = safeRequire(path.join(helpersDir, 'memory.cjs'));
 const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));
+const agentBridge = safeRequire(path.join(helpersDir, 'agent-bridge-hook.cjs'));
 
 // ── Intelligence timeout protection (fixes #1530, #1531) ───────────────────
 var INTELLIGENCE_TIMEOUT_MS = 3000;
@@ -143,19 +144,23 @@ const handlers = {
     } else {
       console.log('[INFO] Router not available, using default routing');
     }
-    // Agentic prompts → remind the main agent to actually USE Swarmdo: spawn
-    // Claude Code agents AND bridge them so Swarmdo tracks the work and
-    // auto-forms a swarm. Advisory + fully guarded — never breaks the prompt.
+    // Agentic prompts → suggest spawning a swarm, and which roles. Swarmdo
+    // cannot call Claude Code's Agent tool itself, so this advisory is the only
+    // way it can ask. Fully guarded — never breaks the prompt.
+    //
+    // Deliberately does NOT mention `agent bridge register` (#108): the
+    // SubagentStart hook registers every subagent on spawn, so telling the main
+    // agent to register by hand is both wrong and redundant work. This fires on
+    // every agentic prompt, so it is kept to one line — the three lines of
+    // manual-registration instructions it replaced were pure token cost.
     try {
       if (router && router.classifyAgentic) {
         const intent = router.classifyAgentic(prompt);
         if (intent.requiresAgents) {
           const roles = intent.roles.join(', ');
           console.log('');
-          console.log('[SWARMDO] Agentic task — use the swarm: after you spawn Claude Code agents,');
-          console.log('  register each so Swarmdo tracks them and auto-forms a swarm from your config:');
-          console.log('    swarmdo agent bridge register -n <agent-name> -t <role> -s <session>');
-          console.log('  suggested roles: ' + roles + '   ·   then: swarmdo agent bridge list / swarm status');
+          console.log('[SWARMDO] Agentic task — consider spawning agents: ' + roles
+            + '  (auto-registered on spawn; see `swarmdo swarm status`)');
         }
       }
     } catch (e) { /* advisory only — never break the prompt */ }
@@ -270,6 +275,27 @@ const handlers = {
     console.log('[OK] Status check');
   },
 
+  // SubagentStart — bind the spawned Claude Code subagent into Swarmdo's
+  // canonical registry so `swarmdo agent list` and the statusline's
+  // `🐝 Swarms N   🤖 Agents M` reflect agents that actually exist (#108).
+  // Registering also auto-forms the swarm, so both counters move.
+  'agent-register': () => {
+    if (!agentBridge) return;
+    if (!agentBridge.isSubagentEvent(hookInput)) return; // main-thread call
+    var ok = agentBridge.register(hookInput);
+    console.log(ok
+      ? '[OK] Bridged subagent ' + (hookInput.agent_type || 'agent') + ' into Swarmdo'
+      : '[WARN] Could not bridge subagent (no installed CLI found)');
+  },
+
+  // SubagentStop — mark the bound record terminated so the Agents count
+  // decrements. Same deterministic id the register side derived (#108).
+  'agent-terminate': () => {
+    if (!agentBridge) return;
+    if (!agentBridge.isSubagentEvent(hookInput)) return;
+    agentBridge.terminate(hookInput);
+  },
+
   'stats': () => {
     if (intelligence && intelligence.stats) {
       intelligence.stats(args.includes('--json'));
@@ -288,7 +314,7 @@ if (command && handlers[command]) {
   } else if (command) {
     console.log('[OK] Hook: ' + command);
   } else {
-    console.log('Usage: hook-handler.cjs <route|pre-bash|post-edit|session-restore|session-end|pre-task|post-task|compact-manual|compact-auto|status|stats>');
+    console.log('Usage: hook-handler.cjs <route|pre-bash|post-edit|session-restore|session-end|pre-task|post-task|agent-register|agent-terminate|compact-manual|compact-auto|status|stats>');
   }
 }
 

package/.claude/settings.json

@@ -144,6 +144,17 @@
         ]
       }
     ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/helpers/hook-handler.cjs\" agent-register",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
     "SubagentStop": [
       {
         "hooks": [
@@ -151,6 +162,11 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/helpers/hook-handler.cjs\" post-task",
             "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/helpers/hook-handler.cjs\" agent-terminate",
+            "timeout": 5000
           }
         ]
       }

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh run *)"
+    ]
+  }
+}

package/README.md

@@ -2,7 +2,7 @@
 
 [![swarmdo](swarmdo/assets/brand/logo-full.svg)](https://swarmdo.com)
 
-[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.58.15-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
+[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.58.23-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://github.com/SwarmDo/swarmdo/blob/main/LICENSE)
 [![Website](https://img.shields.io/badge/swarmdo.com-e2a33c?style=for-the-badge&logoColor=black)](https://swarmdo.com)
 [![Star on GitHub](https://img.shields.io/github/stars/SwarmDo/swarmdo?style=for-the-badge&logo=github&color=gold)](https://github.com/SwarmDo/swarmdo)
@@ -294,7 +294,7 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo hidden-coupling` | **Co-change with no import edge** — join the two graphs swarmdo already owns (temporal `coupling` from git + `codegraph`'s import graph) and emit the set difference: file pairs that keep changing together yet nothing in the code links them ("logical minus structural coupling" — a config and its consumers, a schema and its mirror type). The co-edit `affected` can't see. `--since`, `--min-shared`, `--csv`, `--format json`. Grounded in Gall et al. (ICSM 1998). Deterministic |
 | `swarmdo standup` (alias `mine`) | **What did I do?** — your commits since your last working day, grouped by day with a diffstat. **Weekend-aware** (git-standup parity): on Monday it reaches back to Friday, on Sunday to Friday, otherwise to yesterday — one-command recall for a standup or for re-orienting at the start of a session. Defaults to the current git user; `--author <name>`/`--all` for teammates, `--days N` or `--since 2w` to override the window, `--format json`. Pure engine (weekend math + per-day fold) → fixture-tested. Deterministic |
 | `swarmdo commands` (alias `slash`) | **Hot/cold/orphan usage report** for your authored `.claude/` surface — which custom slash-commands (`.claude/commands/**`) and subagents (`.claude/agents/**`) you actually invoke (**hot**, with counts), which are **cold** (defined but never used → prune candidates), and which are **orphan** (invoked but undefined → a typo or a builtin). `config lint` says "are these valid?"; this says "are these used?" — joining the defined files against invocation counts mined from local transcripts (`<command-name>` markers + `subagent_type` fields). `--unused` prints just the prune list, `--unused --strict` is a CI gate (exit 1 if anything's dead), `--all` counts across every project, `--json`. Pure parsers + join → fixture-tested |
-| `swarmdo agent bridge` | **Link Claude Code agents ⇄ Swarmdo** — the fix for "Swarmdo is installed but never actually used." Swarmdo can't call Claude Code's `Agent` tool (only the main loop can), so `agent bridge register -n <name>` binds a real Claude Code agent into Swarmdo's registry (`swarmdo agent list` stops being empty) and **auto-spins-up a swarm from your config, enrolling the agent** — the next bind joins the same swarm. `bridge list` (bound vs native), `bridge sync --live a,b` (reconcile drift), `bridge advise "<prompt>"` (should this warrant a swarm? which roles?). Also MCP tools `agent_bridge_register`/`agent_bridge_list`. Pure engine → 16 tests |
+| `swarmdo agent bridge` | **Link Claude Code agents ⇄ Swarmdo** — the fix for "Swarmdo is installed but never actually used." Swarmdo can't call Claude Code's `Agent` tool (only the main loop can), so `agent bridge register -n <name>` binds a real Claude Code agent into Swarmdo's registry (`swarmdo agent list` stops being empty) and **auto-spins-up a swarm from your config, enrolling the agent** — the next bind joins the same swarm. **Automatic since 1.58.18:** `swarmdo init` wires a `SubagentStart` hook that registers every Claude Code subagent as it spawns, and a `SubagentStop` hook that marks it terminated — so the statusline's `🐝 Swarms N   🤖 Agents M` tracks real agents with no manual step (#108). `bridge list` (bound vs native), `bridge sync --live a,b` (reconcile drift), `bridge advise "<prompt>"` (should this warrant a swarm? which roles?). Also MCP tools `agent_bridge_register`/`agent_bridge_list`. Pure engine → 16 tests |
 | `swarmdo testreport` | **JUnit/TAP → failure digest** — turn raw test-result files into the exact failing test names + `file:line` + assertion messages, instead of scanning hundreds of log lines. The front-half of the test→fix loop: feed the failures straight into `repair`. Reads a file, a directory, or stdin; `--ci` exits 1 on any failure, `--format json`. Also an MCP tool (`testreport`). Deterministic |
 | `swarmdo integrations` (alias `integrate`) | **Use swarmdo from Codex CLI, GitHub Copilot CLI, and pi** — one command wires AGENTS.md + each CLI's MCP config (idempotent, dry-run first, never touches your Claude Code setup) |
 | OpenRouter model pool | **Let swarms pick from any models you configure** — declare tier-mapped OpenRouter models in `swarmdo.config.json`; the router Thompson-samples among them per task and the execution layer dispatches the winner |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmdo",
-  "version": "1.58.15",
+  "version": "1.58.23",
   "description": "Swarmdo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@swarmdo/cli/.claude/helpers/agent-bridge-hook.cjs

@@ -0,0 +1,174 @@
+/**
+ * agent-bridge-hook.cjs — bind real Claude Code subagents into Swarmdo's
+ * canonical agent registry, automatically.
+ *
+ * #108. `src/agent-bridge/bridge.ts` was written to solve "a session can run
+ * four Claude Code agents while `swarmdo agent list` stays empty", and is pure
+ * by design because "All fs / MCP / spawning lives in the command + hook
+ * layers". The command layer got built (`swarmdo agent bridge register`); the
+ * hook layer never did. So nothing ever registered a Task/Agent-tool subagent,
+ * `.swarmdo/agents/store.json` stayed `{"agents":{}}`, and the statusline's
+ * `🐝 Swarms N   🤖 Agents M` sat at 0/0 forever. This file is that missing
+ * hook layer.
+ *
+ * Why shell out to the CLI instead of writing the store here: registering is
+ * not just a store write — `agent_bridge_register` also auto-forms a swarm from
+ * config and enrolls the agent (agent-tools.ts:462), which is what makes the
+ * Swarms counter move too. bridge.ts's own rule is to go through the canonical
+ * registerAgent path — "NO parallel store". Reimplementing that in CJS would
+ * fork the registry. The CLI costs ~850ms to boot (it loads ONNX), far too slow
+ * to block every subagent spawn, so calls are fired detached and unref'd: the
+ * hook returns immediately and the registry lands ~1s later. The statusline
+ * polls every 5s, so eventual consistency is invisible here.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+/**
+ * Mirror of src/agent-bridge/bridge.ts `bridgeAgentId` — kept in sync by hand,
+ * because this hook is standalone CommonJS and cannot import the ESM engine
+ * (the same constraint router.cjs already works under for classifyPrompt).
+ * __tests__/agent-bridge-hook.test.ts asserts the two implementations agree.
+ *
+ * Deterministic, so SubagentStart and SubagentStop derive the SAME id from the
+ * same agent_id and the stop reliably terminates the record the start created.
+ */
+function bridgeAgentId(d) {
+  const sess = d.sessionId
+    ? d.sessionId.replace(/[^A-Za-z0-9]/g, '').slice(0, 8) || 'nosess'
+    : 'nosess';
+  const safe = String(d.name || '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'agent';
+  return `cc-${sess}-${safe}`;
+}
+
+/**
+ * Locate an installed CLI bin. Mirror of statusline.cjs resolveCliBin() — same
+ * candidate order, same reason (#2337): never `npx @latest` from a hook.
+ * Returns null when nothing is installed, in which case we no-op rather than
+ * pay a registry round-trip on every subagent spawn.
+ */
+function resolveCliBin(cwd) {
+  try {
+    const home = os.homedir();
+    const base = cwd || process.cwd();
+    const candidates = [
+      path.join(home, '.claude', 'plugins', 'marketplaces', 'swarmdo', 'bin', 'cli.js'),
+      path.join(base, 'node_modules', '@swarmdo', 'cli', 'bin', 'cli.js'),
+      path.join(base, 'node_modules', 'swarmdo', 'bin', 'cli.js'),
+      path.join(base, 'v3', '@swarmdo', 'cli', 'bin', 'cli.js'),
+    ];
+    try {
+      const binDir = path.dirname(process.execPath);
+      const globalModuleDirs = [
+        path.join(binDir, '..', 'lib', 'node_modules'),
+        path.join(binDir, 'node_modules'),
+        '/opt/homebrew/lib/node_modules',
+        '/usr/local/lib/node_modules',
+      ];
+      for (const prefix of [process.env.npm_config_prefix, process.env.PREFIX, path.join(home, '.npm-global')]) {
+        if (prefix) globalModuleDirs.push(path.join(prefix, 'lib', 'node_modules'));
+      }
+      for (const gm of globalModuleDirs) {
+        candidates.push(
+          path.join(gm, 'swarmdo', 'bin', 'cli.js'),
+          path.join(gm, '@swarmdo', 'cli', 'bin', 'cli.js'),
+        );
+      }
+    } catch { /* ignore */ }
+    for (const p of candidates) {
+      if (fs.existsSync(p)) return p;
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+/**
+ * Is this hook payload a real subagent event we should act on? `agent_id` is
+ * present ONLY when the hook fires for a subagent, so it doubles as the guard
+ * against main-thread invocations. Pure.
+ */
+function isSubagentEvent(hookInput) {
+  const id = hookInput && (hookInput.agent_id || hookInput.agentId);
+  return typeof id === 'string' && id.length > 0;
+}
+
+/**
+ * Build the `agent bridge register` argv for a SubagentStart payload, or null
+ * when the payload is not a subagent event. Pure — the spawn happens in
+ * register(). Registering is idempotent on name+session, so a duplicate
+ * SubagentStart updates the bound record rather than forking a second one.
+ */
+function buildRegisterArgs(hookInput) {
+  if (!isSubagentEvent(hookInput)) return null;
+  const agentId = hookInput.agent_id || hookInput.agentId;
+  const sessionId = hookInput.session_id || hookInput.sessionId || '';
+  const agentType = hookInput.agent_type || hookInput.agentType || 'general-purpose';
+  const args = ['agent', 'bridge', 'register', '-n', agentId, '-t', agentType];
+  if (sessionId) args.push('-s', sessionId);
+  return args;
+}
+
+/**
+ * Build the `agent stop` argv for a SubagentStop payload, or null when the
+ * payload is not a subagent event. `agent stop` sets status='terminated'
+ * (agent-tools.ts:721), which is precisely what computeSwarmStatus filters on,
+ * so the Agents count decrements when a subagent finishes. `-f` because a hook
+ * has no TTY and must not hit the interactive confirm. Pure.
+ */
+function buildTerminateArgs(hookInput) {
+  if (!isSubagentEvent(hookInput)) return null;
+  const id = bridgeAgentId({
+    name: hookInput.agent_id || hookInput.agentId,
+    sessionId: hookInput.session_id || hookInput.sessionId,
+  });
+  return ['agent', 'stop', id, '-f'];
+}
+
+/**
+ * Fire a CLI subcommand and forget it. Detached + unref'd + stdio ignored so
+ * the hook process can exit immediately without waiting on the CLI's ~850ms
+ * boot, and without the child dying alongside it.
+ */
+function spawnDetached(args, cwd) {
+  const cliBin = resolveCliBin(cwd);
+  if (!cliBin) return false;
+  try {
+    const child = spawn(process.execPath, [cliBin, ...args], {
+      cwd: cwd || process.cwd(),
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** SubagentStart → bind the subagent (and auto-form its swarm). */
+function register(hookInput, cwd) {
+  const args = buildRegisterArgs(hookInput);
+  if (!args) return false;
+  return spawnDetached(args, cwd || (hookInput && hookInput.cwd));
+}
+
+/** SubagentStop → mark the bound record terminated. */
+function terminate(hookInput, cwd) {
+  const args = buildTerminateArgs(hookInput);
+  if (!args) return false;
+  return spawnDetached(args, cwd || (hookInput && hookInput.cwd));
+}
+
+module.exports = {
+  bridgeAgentId,
+  resolveCliBin,
+  isSubagentEvent,
+  buildRegisterArgs,
+  buildTerminateArgs,
+  spawnDetached,
+  register,
+  terminate,
+};