claude-code-swarm 0.3.24 → 0.3.26

package/e2e/tier7-loadout-live.test.mjs

@@ -0,0 +1,221 @@
+/**
+ * Tier 7: Live Loadout E2E Tests
+ *
+ * Full end-to-end tests with a LIVE Claude Code instance to verify the
+ * loadout-consumer integration designed in docs/loadout-consumer-design.md.
+ *
+ * These tests cover the Claude-Code-side unknowns that pure-function +
+ * subprocess tests cannot prove:
+ *   1. Claude Code discovers file-based sub-agents at `.claude/agents/`
+ *      with the rich frontmatter we generate (mcpServers, hooks, etc.)
+ *   3. PreToolUse hooks declared in sub-agent frontmatter fire, and the
+ *      `env:` field propagates to the hook subprocess. This is the
+ *      critical Open Verification #3 from the design doc.
+ *
+ * Gated behind LIVE_AGENT_TEST=1 — makes real LLM calls (~$1-2 per run).
+ *
+ * Run:
+ *   LIVE_AGENT_TEST=1 npx vitest run --config e2e/vitest.config.e2e.mjs \
+ *     e2e/tier7-loadout-live.test.mjs
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import fs from "fs";
+import path from "path";
+import { execFileSync } from "child_process";
+import { fileURLToPath } from "url";
+import { runClaude, CLI_AVAILABLE, PLUGIN_DIR } from "./helpers/cli.mjs";
+import { createWorkspace } from "./helpers/workspace.mjs";
+import { cleanupWorkspace } from "./helpers/cleanup.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LIVE = !!process.env.LIVE_AGENT_TEST;
+
+const LOADOUT_DEMO = path.resolve(
+  __dirname,
+  "..",
+  "..",
+  "openteams",
+  "examples",
+  "loadout-demo"
+);
+
+const DEMO_AVAILABLE = fs.existsSync(LOADOUT_DEMO);
+
+// ────────────────────────────────────────────────────────────────
+// Test 1 — Claude Code discovers generated AGENT.md sub-agents
+// ────────────────────────────────────────────────────────────────
+
+describe.skipIf(!LIVE || !CLI_AVAILABLE || !DEMO_AVAILABLE)(
+  "tier7: loadout live — file-based sub-agent discovery",
+  { timeout: 180_000 },
+  () => {
+    let workspace;
+
+    beforeAll(async () => {
+      workspace = createWorkspace({
+        prefix: "swarm-loadout-live-disco-",
+        config: { template: LOADOUT_DEMO },
+      });
+
+      // Materialize the loadout-demo team into .claude/agents/
+      const agentsDir = path.join(workspace.dir, ".claude", "agents");
+      execFileSync(
+        "node",
+        [
+          path.join(PLUGIN_DIR, "scripts", "generate-agents.mjs"),
+          LOADOUT_DEMO,
+          agentsDir,
+        ],
+        { stdio: "ignore", timeout: 30_000 }
+      );
+    });
+
+    afterAll(() => {
+      if (workspace) cleanupWorkspace(workspace.dir);
+    });
+
+    it("writes AGENT.md files with expected names", () => {
+      const agentsDir = path.join(workspace.dir, ".claude", "agents");
+      expect(
+        fs.existsSync(path.join(agentsDir, "reviewer", "AGENT.md"))
+      ).toBe(true);
+      expect(
+        fs.existsSync(path.join(agentsDir, "implementer", "AGENT.md"))
+      ).toBe(true);
+    });
+
+    it("Claude Code accepts the frontmatter and lists our sub-agents", async () => {
+      const { messages, result, logFile } = await runClaude(
+        "List the names of all sub-agents available to you in this project " +
+          "(look at .claude/agents/). Respond with a comma-separated list " +
+          "of just the sub-agent names, nothing else.",
+        {
+          cwd: workspace.dir,
+          maxTurns: 5,
+          maxBudgetUsd: "0.30",
+          label: "tier7-disco",
+        }
+      );
+
+      expect(result, `see log: ${logFile}`).toBeTruthy();
+      const resultText = JSON.stringify(result || {}) + JSON.stringify(messages);
+
+      // The generated sub-agents should appear in the response.
+      // Claude Code auto-resolves .claude/agents/<dir>/AGENT.md as <dir>.
+      expect(
+        resultText,
+        `Expected Claude to list sub-agents; see log: ${logFile}`
+      ).toMatch(/reviewer/i);
+      expect(resultText).toMatch(/implementer/i);
+    });
+  }
+);
+
+// ────────────────────────────────────────────────────────────────
+// Test 3 — PreToolUse hook with `env:` propagates to subprocess
+//
+// This is the critical Open Verification from the design doc.
+// If this passes, the whole non-invasive scope-check enforcement
+// strategy works. If it fails, we need a fallback (CLI args instead
+// of env vars in the hook command).
+// ────────────────────────────────────────────────────────────────
+
+describe.skipIf(!LIVE || !CLI_AVAILABLE)(
+  "tier7: loadout live — PreToolUse hook env: in sub-agent frontmatter",
+  { timeout: 180_000 },
+  () => {
+    let workspace;
+    let probePath;
+    let hookScriptPath;
+
+    beforeAll(async () => {
+      workspace = createWorkspace({
+        prefix: "swarm-loadout-live-hook-",
+        config: { template: "" },
+      });
+
+      probePath = path.join(workspace.dir, "hook-probe.log");
+      hookScriptPath = path.join(workspace.dir, "log-env.sh");
+
+      // Hook script: write the env vars we care about to a probe file.
+      // Exit 0 (allow) so the tool call proceeds normally.
+      fs.writeFileSync(
+        hookScriptPath,
+        [
+          "#!/usr/bin/env bash",
+          `echo "PROBE_KEY=\${PROBE_KEY:-MISSING}" >> "${probePath}"`,
+          `echo "ROLE_NAME=\${ROLE_NAME:-MISSING}" >> "${probePath}"`,
+          `echo "--tool=\${CLAUDE_TOOL_NAME:-?}" >> "${probePath}"`,
+          "exit 0",
+        ].join("\n"),
+        { mode: 0o755 }
+      );
+
+      // Write a minimal sub-agent with a Bash PreToolUse hook that
+      // uses env: to inject PROBE_KEY and ROLE_NAME.
+      const agentDir = path.join(workspace.dir, ".claude", "agents");
+      fs.mkdirSync(agentDir, { recursive: true });
+      const agentMd = [
+        "---",
+        "name: probe-agent",
+        'description: "Probe agent for hook env: verification"',
+        "tools:",
+        "  - Bash",
+        "hooks:",
+        "  PreToolUse:",
+        '    - matcher: "Bash"',
+        "      hooks:",
+        "        - type: command",
+        `          command: ${hookScriptPath}`,
+        "          env:",
+        "            PROBE_KEY: probe-value-xyz-42",
+        "            ROLE_NAME: probe-role",
+        "---",
+        "",
+        "# Probe Agent",
+        "",
+        "When asked to run a shell command, run it via Bash. No commentary.",
+        "",
+      ].join("\n");
+      fs.writeFileSync(path.join(agentDir, "probe-agent.md"), agentMd);
+    });
+
+    afterAll(() => {
+      if (workspace) cleanupWorkspace(workspace.dir);
+    });
+
+    it("invokes a Bash-using sub-agent and captures hook env vars", async () => {
+      const { messages, result, logFile } = await runClaude(
+        "Use the Task tool to delegate to sub-agent 'probe-agent' with the task: " +
+          "\"Run the shell command: echo hello-from-probe\"",
+        {
+          cwd: workspace.dir,
+          maxTurns: 6,
+          maxBudgetUsd: "0.30",
+          label: "tier7-hook-env",
+        }
+      );
+
+      expect(result, `see log: ${logFile}`).toBeTruthy();
+
+      // The hook should have fired at least once — probe log must exist and
+      // contain the specific env value we set in the sub-agent frontmatter.
+      expect(
+        fs.existsSync(probePath),
+        `Hook probe log missing at ${probePath}. See runClaude log: ${logFile}. ` +
+          `This is the key assertion — if the file is absent, Claude Code did not ` +
+          `invoke the PreToolUse hook from the sub-agent's frontmatter.`
+      ).toBe(true);
+
+      const probe = fs.readFileSync(probePath, "utf-8");
+      expect(
+        probe,
+        `Env var PROBE_KEY did not propagate. Probe contents: ${probe}. ` +
+          `Log: ${logFile}. This means Claude Code does not honor \`env:\` in ` +
+          `sub-agent hook frontmatter, and we need the CLI-arg fallback.`
+      ).toContain("PROBE_KEY=probe-value-xyz-42");
+      expect(probe).toContain("ROLE_NAME=probe-role");
+    });
+  }
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {
@@ -53,10 +53,10 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "agent-inbox": "^0.1.9",
+    "agent-inbox": "^0.2.3",
     "minimem": "^0.1.1",
     "opentasks": "^0.1.2",
-    "skill-tree": "^0.1.5",
+    "skill-tree": "^0.2.0",
     "vitest": "^4.0.18",
     "ws": "^8.0.0"
   }

package/scripts/map-hook.mjs

@@ -77,7 +77,29 @@ async function handleInject(hookData, sessionId) {
   const sPaths = sessionPaths(sessionId);
   const config = readConfig();
 
-  if (!config.inbox?.enabled) return;
+  // Check for dispatch thread nudges (advisory push from hub).
+  // Nudges arrive via x-dispatch/nudge MAP notifications; the sidecar
+  // stores them until this hook drains them. We check nudges even when
+  // inbox is disabled — the nudge path is independent.
+  // Uses sendToInbox (which waits for a response) on the sidecar socket.
+  let nudgeOutput = "";
+  try {
+    const nudgeResp = await sendToInbox(
+      { action: "check-nudge" },
+      sPaths.socketPath,
+    );
+    if (nudgeResp && nudgeResp.ok && nudgeResp.nudges?.length > 0) {
+      const ids = nudgeResp.nudges.map((n) => n.dispatch_id).join(", ");
+      nudgeOutput = `\n<dispatch-thread-nudge>\nYou have pending messages in dispatch coordination thread(s): ${ids}. Check your inbox for new turns.\n</dispatch-thread-nudge>\n`;
+    }
+  } catch {
+    // Best effort — nudge is advisory
+  }
+
+  if (!config.inbox?.enabled) {
+    if (nudgeOutput) process.stdout.write(nudgeOutput);
+    return;
+  }
 
   // Only check messages addressed to the main agent (not all scope messages).
   // Per-agent messages stay in storage for agents to pull via MCP tools.
@@ -89,10 +111,9 @@ async function handleInject(hookData, sessionId) {
     { action: "check_inbox", agentId: mainAgentId, scope, unreadOnly: true, clear: true },
     sPaths.inboxSocketPath
   );
-  if (!resp || !resp.ok || !resp.messages?.length) return;
 
   // Forward task.* events to opentasks graph if enabled
-  if (config.opentasks?.enabled) {
+  if (resp?.ok && resp.messages?.length && config.opentasks?.enabled) {
     const otSocketPath = findSocketPath();
     const taskEvents = resp.messages.filter(
       (m) => m.content?.type === "event" && m.content?.event?.startsWith("task.")
@@ -102,8 +123,12 @@ async function handleInject(hookData, sessionId) {
     }
   }
 
-  const output = formatInboxAsMarkdown(resp.messages);
-  if (output) process.stdout.write(output);
+  const inboxOutput = resp?.ok && resp.messages?.length
+    ? formatInboxAsMarkdown(resp.messages)
+    : "";
+
+  const output = (nudgeOutput + (inboxOutput || "")).trim();
+  if (output) process.stdout.write(output + "\n");
 }
 
 async function handleTurnCompleted(hookData, sessionId) {

package/scripts/map-sidecar.mjs

@@ -425,6 +425,34 @@ function registerContentHandler(conn) {
   });
 }
 
+/**
+ * Register the x-dispatch/nudge notification handler on a connection.
+ * When the hub sends a nudge (a dispatch thread received a new turn),
+ * the sidecar stores the nudge so the UserPromptSubmit hook can inject
+ * a hint about pending messages.
+ */
+function registerNudgeHandler(conn) {
+  if (!conn || typeof conn.onNotification !== "function") return;
+
+  conn.onNotification("x-dispatch/nudge", (params) => {
+    const dispatchId = params?.dispatch_id;
+    const conversationId = params?.conversation_id;
+    if (!dispatchId) return;
+
+    log.info("dispatch nudge received", { dispatchId, conversationId });
+    resetInactivityTimer();
+
+    // Store the nudge via the command handler's nudge command.
+    // Use a fake client since we don't need the response.
+    if (commandHandler) {
+      commandHandler(
+        { action: "nudge", dispatch_id: dispatchId, conversation_id: conversationId },
+        { write: () => {}, writable: true },
+      );
+    }
+  });
+}
+
 async function startWebSocketTransport() {
   connection = await connectToMAP({
     server: MAP_SERVER,
@@ -557,6 +585,10 @@ async function main() {
     return commandHandler(command, client);
   });
 
+  // Register dispatch nudge handler — must come after commandHandler is created
+  // so the notification can store nudge state via the command handler.
+  registerNudgeHandler(connection);
+
   // Start memory file watcher if minimem is enabled
   const sidecarConfig = readConfig();
   if (sidecarConfig.minimem?.enabled) {

package/scripts/scope-check.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * scope-check.mjs — Generic PreToolUse hook for enforcing per-role MCP
+ * scope declared in a swarm-generated scope file.
+ *
+ * Invoked per sub-agent via frontmatter:
+ *
+ *   hooks:
+ *     PreToolUse:
+ *       - matcher: "mcp__.*"
+ *         hooks:
+ *           - type: command
+ *             command: ${CLAUDE_PLUGIN_ROOT}/scripts/scope-check.mjs
+ *             env:
+ *               SCOPE_FILE: .swarm/.../scope/<role>.json
+ *               ROLE_NAME:  <role>
+ *
+ * Input: tool-call JSON via stdin (Claude Code hook protocol).
+ * Output:
+ *   exit 0 → allow
+ *   exit 2 → block, with human-readable reason printed to stderr
+ *
+ * See docs/loadout-consumer-design.md for the larger design.
+ */
+
+import fs from "fs";
+
+const MCP_PREFIX = "mcp__";
+
+async function main() {
+  const input = await readStdin();
+  let parsed;
+  try {
+    parsed = input ? JSON.parse(input) : {};
+  } catch {
+    // Can't parse input — allow, not our place to block on hook-protocol glitches.
+    process.exit(0);
+  }
+
+  const toolName = parsed?.tool_name ?? "";
+  if (!toolName.startsWith(MCP_PREFIX)) {
+    // Shouldn't happen under the mcp__.* matcher, but be defensive.
+    process.exit(0);
+  }
+
+  const parts = toolName.slice(MCP_PREFIX.length).split("__");
+  if (parts.length < 2) {
+    // Malformed MCP tool name — allow, nothing to check.
+    process.exit(0);
+  }
+  const server = parts[0];
+  const tool = parts.slice(1).join("__");
+
+  const scopeFilePath = process.env.SCOPE_FILE;
+  if (!scopeFilePath) {
+    // No scope file configured — nothing to enforce, allow.
+    process.exit(0);
+  }
+
+  let scopeDoc;
+  try {
+    scopeDoc = JSON.parse(fs.readFileSync(scopeFilePath, "utf-8"));
+  } catch (err) {
+    writeError(
+      `scope-check: could not read scope file at ${scopeFilePath} ` +
+        `(${err.message}). Allowing tool call — install claude-code-swarm ` +
+        `correctly or remove the hook to silence this.`
+    );
+    process.exit(0);
+  }
+
+  const scopeList = Array.isArray(scopeDoc?.scope) ? scopeDoc.scope : [];
+  const entry = scopeList.find((s) => s?.server === server);
+
+  // If the server is referenced in scope but restricted → enforce.
+  // If the server is not in scope at all, Claude Code's own `mcpServers:`
+  // allowlist should have blocked this already; we don't second-guess it.
+  if (!entry) {
+    process.exit(0);
+  }
+
+  const role = process.env.ROLE_NAME || scopeDoc?.role || "(unknown)";
+
+  if (Array.isArray(entry.exclude) && entry.exclude.includes(tool)) {
+    writeError(
+      `Tool ${toolName} is denied for role "${role}" (listed in scope exclude).`
+    );
+    process.exit(2);
+  }
+
+  if (Array.isArray(entry.tools) && entry.tools.length > 0) {
+    if (!entry.tools.includes(tool)) {
+      writeError(
+        `Tool ${toolName} is not in the scope allowlist for role "${role}" ` +
+          `(allowed: ${entry.tools.join(", ")}).`
+      );
+      process.exit(2);
+    }
+  }
+
+  // No restriction hit — allow.
+  process.exit(0);
+}
+
+function writeError(msg) {
+  process.stderr.write(msg + "\n");
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    // If stdin is a TTY we're running interactively — no input to consume.
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+    let buf = "";
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on("end", () => resolve(buf));
+    process.stdin.on("error", reject);
+  });
+}
+
+main().catch((err) => {
+  // On any unexpected error, fail open (allow) with a message.
+  // Hook errors should not break the agent — blocking a valid tool
+  // call because our hook crashed is worse than allowing an out-of-scope one.
+  writeError(`scope-check: unexpected error — ${err?.message ?? err}`);
+  process.exit(0);
+});

package/skills/swarm-mcp/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: swarm-mcp
+description: Inspect and optionally install MCP providers declared by the current swarm team. Non-invasive by default — reports status without modifying user MCP configuration unless explicitly requested.
+user_invocable: true
+argument: optional
+---
+
+# /swarm-mcp — Inspect and Manage Team MCP Providers
+
+You manage the **MCP (Model Context Protocol) surface** for the configured swarm team. Your role is to inspect declared providers, report health, and optionally install or sync with explicit user consent.
+
+## Design principles
+
+- **Non-invasive by default.** Do NOT modify `.mcp.json`, `.claude/settings.json`, `.claude/settings.local.json`, or user-global config without explicit user opt-in.
+- **Check-and-notify over auto-install.** Surface discrepancies. Let the user decide.
+- **Confirmation before any write.** Always show a diff preview and wait for explicit approval.
+
+## Artifact sources
+
+The swarm team loader (`scripts/team-loader.mjs`) has already populated the following cache files (one pass, at session start):
+
+- `.swarm/claude-swarm/tmp/teams/<template>/mcp-providers.json` — team-declared provider install specs
+- `.swarm/claude-swarm/tmp/teams/<template>/mcp-health.json` — pre-computed health report (regenerated each session)
+- `.swarm/claude-swarm/tmp/teams/<template>/scope/<role>.json` — per-role scope files consumed by the PreToolUse hook
+- `.swarm/claude-swarm/tmp/teams/<template>/loadouts/<role>.json` — debug view of resolved per-role loadout
+
+Do NOT regenerate these files. They're owned by the team-loader.
+
+## Subcommands
+
+Parse `$ARGUMENTS` as the first token to determine which subcommand to run.
+
+### `check` — Dry-run health report
+
+Purpose: show declared providers vs active set, flag missing / refs / disabled / orphaned scope references.
+
+Steps:
+1. Read `.swarm/claude-swarm/tmp/teams/<template>/mcp-health.json`. If missing, ask the user to reload the team (`/swarm <template>`) — the loader populates this file.
+2. Render the report using the classification fields:
+   - `ok[]`   — servers declared AND active (checkmark + source)
+   - `missing[]` — declared, not active (warning + suggest `install`)
+   - `refs[]` — symbolic refs deferred to consumer (inform)
+   - `disabled[]` — declared with `disabled: true`
+   - `activeOnly[]` — active but not declared (informational)
+   - `orphanedReferences[]` — loadout scope references not backed by anything
+3. Print a compact table. Do NOT write any files.
+
+### `install [name]` — Explicit MCP install
+
+Purpose: append a team-declared provider (from `mcp-providers.json`) to the project `.mcp.json` after explicit user confirmation. If `[name]` is omitted, list installable entries and ask the user to pick.
+
+Steps:
+1. Read `.swarm/claude-swarm/tmp/teams/<template>/mcp-providers.json`.
+2. Read (or initialize) project-root `.mcp.json`.
+3. For each requested `name`:
+   a. Strip openteams-specific fields (`ref`, `description`, `disabled`) from the provider spec.
+   b. If `.mcp.json` already contains the same name, diff the specs and show both to the user. Ask whether to overwrite.
+   c. Show the full diff that would land in `.mcp.json`.
+   d. Wait for explicit user approval (`yes` / `install` / `y`) before writing.
+4. Write `.mcp.json` atomically. Inform the user they will need to restart Claude Code for the new server to connect.
+
+Refuse to proceed if:
+- The provider has `disabled: true` (skip with a message)
+- The provider has `ref:` but no bundled registry to resolve it (skip with a suggestion to run `/swarm-mcp resolve-ref`)
+- The user hasn't confirmed
+
+### `permissions-sync` — Explicit permissions sync
+
+Purpose: merge loadout-driven permissions into `.claude/settings.local.json` under a clearly-marked swarm block. `settings.local.json` is user-owned and typically gitignored, so we never touch `.claude/settings.json`.
+
+Steps:
+1. Collect the union of all roles' permissions:
+   - `.swarm/claude-swarm/tmp/teams/<template>/scope/<role>.json` → `permissions.{allow,deny,ask}`
+   - Scope entries → translated to `mcp__<server>__*` (for bare server access) and `mcp__<server>__<tool>` (for exclude entries)
+2. Read `.claude/settings.local.json` (or initialize an empty object if absent).
+3. Locate or create a marked block:
+   ```json
+   "permissions": {
+     "allow": [
+       "/* swarm:<template>:start */",
+       "...",
+       "/* swarm:<template>:end */"
+     ]
+   }
+   ```
+   (If JSON doesn't tolerate comments, use a sentinel entry like `"// swarm:<template>:start"`.)
+4. Replace the marked block's contents; preserve everything outside the sentinel fences.
+5. Show the diff, wait for confirmation, write atomically.
+
+### `clean` — Remove swarm-generated agents
+
+Purpose: remove `.claude/agents/<team>-*` files written by swarm, respecting the `generated_by: claude-code-swarm` marker. Never touches hand-authored agents.
+
+Steps:
+1. Scan `.claude/agents/*.md` (or `~/.claude/agents/<project-slug>-<team>-*.md` if the current team uses user scope).
+2. Filter to files whose frontmatter contains:
+   - `generated_by: claude-code-swarm` AND
+   - `team_name: <current-template>` (if `--team` given) or any swarm team (default)
+3. Show the list and confirm with the user before deleting.
+4. Optionally also delete `.swarm/claude-swarm/tmp/teams/<template>/` cache files when `--with-artifacts` is given.
+
+### `resolve-ref <ref>` — (Deferred)
+
+For future use. Currently prints a stub message indicating ref resolution requires an OpenHive hive connection or a bundled registry (not yet shipped).
+
+## Default behavior when no subcommand given
+
+If `$ARGUMENTS` is empty, run the `check` subcommand — the safest and most informative default.
+
+## What you must NOT do
+
+- Do not modify `.mcp.json` without explicit user confirmation
+- Do not modify `.claude/settings.json` (committed project settings) — only `.claude/settings.local.json`
+- Do not touch user-global config in `~/.claude/` without explicit opt-in
+- Do not invoke `install` or `permissions-sync` without a clear user yes
+- Do not re-run the team-loader from inside this skill (`/swarm` or `loadTeam` does that)