claude-code-swarm 0.3.25 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.25",
+  "version": "0.4.0",
   "description": "Launch Claude Code with swarmkit capabilities, including team orchestration, MAP observability, and session tracking.",
   "owner": {
     "name": "alexngai"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-swarm",
   "description": "Spin up Claude Code agent teams from openteams YAML topologies with optional MAP (Multi-Agent Protocol) observability and coordination. Provides hooks for session lifecycle, agent spawn/complete tracking, and a /swarm skill to launch team configurations.",
-  "version": "0.3.25",
+  "version": "0.4.0",
   "author": {
     "name": "alexngai"
   },

package/CLAUDE.md

@@ -226,6 +226,98 @@ Skill-tree options:
 - `basePath` — Path to skill-tree storage directory (default: `.swarm/skill-tree/`)
 - `defaultProfile` — Default profile when no role-specific criteria exist (default: `""`)
 
+### Cascade integration (Phases 1–2)
+```json
+{
+  "template": "gsd",
+  "map": { "server": "ws://localhost:8080" },
+  "cascade": {
+    "enabled": true
+  }
+}
+```
+
+When enabled, the MAP sidecar opens a persistent `git-cascade` tracker
+(`MultiAgentRepoTracker`) in **local mode** as a local state store under
+`.swarm/claude-swarm/tmp/cascade/tracker.db`. On boot it registers the
+repository's current working branch as a local-mode git-cascade stream and
+emits a single `x-cascade/stream.opened` notification over the MAP connection
+so an OpenHive hub's cascade subsystem can observe the swarm.
+
+**Phase 2 — observed git.** The sidecar also runs a poll-based ref watcher
+(`src/cascade-watcher.mjs`). Every ~3s it diffs `git for-each-ref` snapshots
+and, when it detects git activity, emits `x-cascade/*` events with real git
+data: `stream.committed` (per new commit, with message summary / files touched
+/ parent / git-cascade change id), `stream.merged` (for merge commits, with
+best-effort source-stream resolution via the 2nd parent), `stream.pushed`
+(when a remote-tracking ref catches up to a local branch), and `stream.opened`
+(for newly-appeared branches + a connection re-assert on MAP reconnect). The
+watcher is the **detector**; it works fully standalone, emitting unattributed
+events when no attribution is present.
+
+After the ref-diff pass each tick the watcher also probes in-progress
+**merge-conflict** state: a cheap `existsSync` on the worktree-local
+`.git/MERGE_HEAD`. On the off→on transition it records a conflict row
+(`recordObservedConflict` → git-cascade `conflicts.createConflict`) and emits
+`x-cascade/stream.conflicted` with the conflicted files (`git diff
+--name-only --diff-filter=U`), the conflicting commit (`MERGE_HEAD`), the
+target commit (`HEAD`), and `source: "merge"`. On the on→off transition it
+discriminates by HEAD: if HEAD advanced to a commit with ≥2 parents the merge
+was resolved + committed (`resolution_method: "manual"`, or `"agent"` when a
+fresh attribution hint is present) — otherwise the merge was aborted (HEAD
+unchanged → `"abandoned"`, via `conflicts.abandonConflict`). Conflict events
+fire only on transitions, never on every tick while a conflict is open. The
+sidecar advertises `cascade.emitsConflicts: true` honestly off the back of
+this. Rebase-conflict observation (`.git/rebase-merge/`,
+`.git/rebase-apply/`) is a known future expansion — v1 covers `git merge`
+conflicts only.
+
+A `PostToolUse(Bash)` hook supplies **attribution only** — it does not detect
+git. It builds an `{ agentId, taskRef, ts }` hint and pushes it to the sidecar
+via the `cascade-attribution` socket command. The watcher stamps `agent_id` /
+`metadata.task_ref` on emitted events when a fresh hint (within ~30s) exists.
+`taskRef` is correlated against the in-progress opentasks task only when
+`opentasks.enabled`; without opentasks, attribution carries `agent_id` only.
+
+When the watcher detects a branch forked from a tracked branch it links the
+fork: the `x-cascade/stream.opened` event carries `parent_stream` (the parent
+branch's stream id) and the git-cascade tracker DB records the parent edge, so
+an OpenHive hub's PR-stack walker can traverse parent → child.
+
+**Phase 3 — diff serving.** The sidecar wires a diff server
+(`src/cascade-diff-server.mjs`) that registers an inbound `cascade/diff.request`
+handler on the MAP connection, so an OpenHive hub's cascade changelog/diff
+endpoints work for cc-swarm-tracked streams. On a request the server resolves
+the diff with plain git in the repo cwd — cc-swarm runs git-cascade in local
+mode with no worktrees, so the request's `head` / `base` (commit hashes,
+self-identifying) drive `git show <head>` (single commit) or
+`git diff <base>..<head>` (range), with `--name-only` when `files_only` is set
+and a `file_paths` path restriction when present. `files_touched` is always
+computed via `--name-only`. A 50 MB stdout cap and 30 s timeout bound the git
+spawn. The server replies inline (`cascade/diff.response`, `streaming: false`)
+when the raw diff is ≤ 512 KB; larger diffs send a streaming announcement
+(`streaming: true`) followed by 1 MB base64 `cascade/diff.chunk` notifications,
+seq-ordered, with `final: true` + a sha256 over the full payload on the last
+chunk. Any error (bad request, git failure) folds into the typed
+`cascade/diff.response` error variant — the server never throws.
+
+The sidecar declares the `cascade: { canServeDiff: true }` MAP capability at
+registration, **conditional on `cascade.enabled`** — the same gate the diff
+server is wired on. Declaring `canServeDiff` without the server would invite
+`cascade/diff.request` notifications from the hub that time out.
+
+cc-swarm emits `x-cascade/*` events itself over MAP — the tracker is not given
+git-cascade's `emit` callback. Cascade is only meaningful when `map` is enabled
+(there is otherwise no connection to emit on); when `map` is disabled it is an
+inert no-op rather than a hard failure. All cascade work is fully gated on
+`cascade.enabled` and wrapped so a cascade failure can never crash the sidecar.
+
+Cascade options:
+- `enabled` — Enable git-cascade integration (default: `false`)
+
+Requires `git-cascade` (`>= ^0.0.7`), installed on demand via swarmkit during
+bootstrap when `cascade.enabled`.
+
 ### Logging
 ```json
 {
@@ -303,6 +395,7 @@ All config values can be overridden via `SWARM_*` environment variables. Priorit
 | `skilltree.enabled` | `SWARM_SKILLTREE_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `skilltree.basePath` | `SWARM_SKILLTREE_BASE_PATH` | string | `""` |
 | `skilltree.defaultProfile` | `SWARM_SKILLTREE_DEFAULT_PROFILE` | string | `""` |
+| `cascade.enabled` | `SWARM_CASCADE_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `mesh.enabled` | `SWARM_MESH_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `mesh.peerId` | `SWARM_MESH_PEER_ID` | string | `""` |
 | `mesh.mapServer` | `SWARM_MESH_MAP_SERVER` | string | `""` |
@@ -404,6 +497,7 @@ Both modes:
 - `trajectory: { canReport: true, canServeContent: true }` — reports checkpoints, serves transcript content on demand
 - `tasks: { canCreate, canAssign, canUpdate, canList }` — task management
 - `opentasks: { canQuery, canLink, canAnnotate, canTask }` — conditional, when task_graph configured
+- `cascade: { canServeDiff: true }` — conditional, when `cascade.enabled` — sidecar serves unified diffs on demand via `cascade/diff.request` (see Cascade integration above)
 
 Message delivery is **pull-based**: the `UserPromptSubmit` hook reads the inbox on each turn and injects messages into Claude Code's prompt context. No real-time push delivery.
 
@@ -465,6 +559,7 @@ Global (managed by swarmkit, installed on demand during bootstrap):
 - **sessionlog** — git-integrated session capture (installed when `sessionlog.enabled: true`)
 - **minimem** — file-based memory with vector search (installed when `minimem.enabled: true`)
 - **skill-tree** — versioned skill library with serving layer (installed when `skilltree.enabled: true`)
+- **git-cascade** — multi-agent git tracking; local-mode tracker for cascade observability (installed when `cascade.enabled: true`)
 
 Runtime:
 - **Claude Code agent teams** — enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Ngai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/hooks/hooks.json

@@ -80,6 +80,15 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('fs'),p=require('path'),h=require('os').homedir();let c={};try{c=JSON.parse(f.readFileSync('.swarm/claude-swarm/config.json','utf-8'))}catch{try{c=JSON.parse(f.readFileSync(p.join(h,'.claude-swarm','config.json'),'utf-8'))}catch{}};process.exit((c.cascade?.enabled||process.env.SWARM_CASCADE_ENABLED)&&(c.map?.enabled||c.map?.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED)?0:1)\" 2>/dev/null && node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" cascade-bash-attribution"
+          }
+        ]
+      },
       {
         "matcher": "TaskCreate",
         "hooks": [

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.25",
+  "version": "0.4.0",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
+  "author": "Alex Ngai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexngai/claude-code-swarm.git"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.mjs",
@@ -24,6 +30,7 @@
   },
   "peerDependencies": {
     "agent-inbox": "*",
+    "git-cascade": ">=0.0.9",
     "opentasks": ">=0.1.1",
     "swarmkit": "*"
   },
@@ -31,6 +38,9 @@
     "agent-inbox": {
       "optional": true
     },
+    "git-cascade": {
+      "optional": true
+    },
     "opentasks": {
       "optional": true
     }
@@ -45,6 +55,7 @@
     "test:e2e:tier4": "vitest run --config e2e/vitest.config.e2e.mjs -t tier4",
     "test:e2e:tier5": "vitest run --config e2e/vitest.config.e2e.mjs -t tier5",
     "test:e2e:tier7": "vitest run --config e2e/vitest.config.e2e.mjs -t tier7",
+    "prepublishOnly": "publint",
     "version:patch": "npm version patch --no-git-tag-version && node scripts/sync-version.mjs",
     "version:minor": "npm version minor --no-git-tag-version && node scripts/sync-version.mjs",
     "version:major": "npm version major --no-git-tag-version && node scripts/sync-version.mjs"
@@ -53,9 +64,11 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "agent-inbox": "^0.1.9",
+    "agent-inbox": "^0.2.3",
+    "git-cascade": "^0.0.9",
     "minimem": "^0.1.1",
     "opentasks": "^0.1.2",
+    "publint": "^0.3.21",
     "skill-tree": "^0.2.0",
     "vitest": "^4.0.18",
     "ws": "^8.0.0"

package/renovate.json5

@@ -0,0 +1,6 @@
+{
+  // Dependency-update policy is shared across the swarm/openhive ecosystem.
+  // See github.com/alexngai/swarm-renovate-config.
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>alexngai/swarm-renovate-config"]
+}

package/scripts/map-hook.mjs

@@ -20,6 +20,7 @@
  *   task-completed      — Complete task in opentasks + emit bridge event
  *   opentasks-mcp-used  — Bridge opentasks MCP tool use → MAP task sync payload
  *   sessionlog-dispatch — Dispatch a sessionlog lifecycle hook via programmatic API
+ *   cascade-bash-attribution — Push a cascade attribution hint to the sidecar
  *
  * Usage: node map-hook.mjs <action>
  *        Hook event data is read from stdin (JSON).
@@ -36,7 +37,7 @@ configureNodePath();
 const log = createLogger("map-hook");
 import { readRoles, matchRole } from "../src/roles.mjs";
 import { formatInboxAsMarkdown } from "../src/inbox.mjs";
-import { sendToInbox } from "../src/sidecar-client.mjs";
+import { sendToInbox, sendToSidecar } from "../src/sidecar-client.mjs";
 import { sessionPaths } from "../src/paths.mjs";
 import {
   sendCommand,
@@ -51,7 +52,7 @@ import {
   buildMinimemBridgeCommand,
 } from "../src/map-events.mjs";
 import { syncSessionlog, dispatchSessionlogHook } from "../src/sessionlog.mjs";
-import { findSocketPath, pushSyncEvent } from "../src/opentasks-client.mjs";
+import { findSocketPath, pushSyncEvent, rpcRequest } from "../src/opentasks-client.mjs";
 
 const action = process.argv[2];
 
@@ -77,7 +78,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 +112,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 +124,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) {
@@ -207,6 +233,60 @@ async function handleMinimemMcpUsed(hookData, sessionId) {
   }
 }
 
+// ── cascade attribution (PostToolUse Bash) ──────────────────────────────────
+//
+// Attribution-only: this does NOT parse the git command or detect git. The
+// cascade-watcher in the sidecar is the detector. This hook just builds an
+// attribution hint { agentId, taskRef, ts } and pushes it to the sidecar as a
+// `cascade-attribution` command — the watcher reads the freshest hint to
+// stamp agent_id / task_ref on observed-git events.
+
+async function handleCascadeBashAttribution(hookData, sessionId) {
+  const config = readConfig();
+  if (!config.cascade?.enabled || !config.map?.enabled) return;
+
+  // Acting agent id — same resolution other hooks use: hook data first,
+  // then env. Falls back to the session id when nothing else identifies it.
+  const agentId =
+    hookData.agent_id ||
+    process.env.CLAUDE_AGENT_ID ||
+    process.env.MACRO_AGENT_ID ||
+    sessionId ||
+    "";
+
+  // taskRef — only correlated when opentasks is enabled. When opentasks is
+  // disabled we skip the query entirely and leave taskRef null; no task
+  // correlation is expected without opentasks (intended).
+  let taskRef = null;
+  if (config.opentasks?.enabled && agentId) {
+    try {
+      const otSocketPath = findSocketPath();
+      const nodes = await rpcRequest(
+        "graph.query",
+        { type: "task", filter: { status: "in_progress", assignee: agentId } },
+        otSocketPath,
+      );
+      const task = Array.isArray(nodes) ? nodes[0] : null;
+      if (task) {
+        // resource_id intentionally omitted — the hub resolves it from the
+        // swarm's registered task graph. Emitting a guessed value causes false
+        // bindings.
+        taskRef = {
+          node_id: task.node_id || task.id || "",
+        };
+      }
+    } catch {
+      // Best-effort — leave taskRef null on any failure.
+    }
+  }
+
+  const sPaths = sessionPaths(sessionId);
+  await sendToSidecar(
+    { action: "cascade-attribution", agentId, taskRef, ts: Date.now() },
+    sPaths.socketPath,
+  );
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -228,6 +308,7 @@ async function main() {
       case "native-task-created": await handleNativeTaskCreated(hookData, sessionId); break;
       case "native-task-updated": await handleNativeTaskUpdated(hookData, sessionId); break;
       case "minimem-mcp-used": await handleMinimemMcpUsed(hookData, sessionId); break;
+      case "cascade-bash-attribution": await handleCascadeBashAttribution(hookData, sessionId); break;
       case "sessionlog-dispatch": await handleSessionlogDispatch(hookData); break;
       default:
         log.warn("unknown action", { action });