@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/install/claude.mjs

@@ -196,7 +196,7 @@ function installOwnedTrees({ pipelineSrc, claudeDir, manifest, adopt }) {
   };
 
   console.log(
-    "  [Claude Code] Installing pipeline commands, refs, scripts, schemas, lib, templates...",
+    "  [Claude Code] Installing pipeline commands, refs, scripts, schemas, office, lib, templates...",
   );
 
   const nsSrc = join(pipelineSrc, "commands", "multi-agent");
@@ -242,6 +242,14 @@ function installOwnedTrees({ pipelineSrc, claudeDir, manifest, adopt }) {
     logs.push(`    -> ${countFiles(schemasSrc)} files copied to ${schemasDest}`);
   });
 
+  // The office panel page, served from ../office beside the scripts directory.
+  const officeSrc = join(pipelineSrc, "office");
+  const officeDest = join(claudeDir, "office");
+  add(officeDest, "office", officeSrc, (staged) => {
+    copyDir(officeSrc, staged);
+    logs.push(`    -> ${countFiles(officeSrc)} files copied to ${officeDest}`);
+  });
+
   for (const [name, src] of [
     ["lib", join(pipelineSrc, "lib")],
     ["templates", join(dirname(pipelineSrc), "install", "templates")],
@@ -315,6 +323,7 @@ function linkOwnedTrees(pipelineSrc, claudeDir) {
     ["multi-agent-refs", join(pipelineSrc, "multi-agent-refs")],
     ["scripts", join(pipelineSrc, "scripts")],
     ["schemas", join(pipelineSrc, "schemas")],
+    ["office", join(pipelineSrc, "office")],
     ["lib", join(pipelineSrc, "lib")],
     ["templates", join(dirname(pipelineSrc), "install", "templates")],
   ];
@@ -837,6 +846,93 @@ export function quotePipelineHookCommands(hooks) {
   return changed;
 }
 
+/**
+ * The run-scoped hooks the installer registers beside the two gates above:
+ * run-stop-guard.sh (Stop) and run-scope-guard.sh (Figma MCP
+ * tools, file edits). Each is silent outside a pipeline run and fails open, so
+ * registering them by default changes nothing until a run is active. The same
+ * entries are in install/templates/claude-hooks.json.
+ */
+export const RUN_HOOKS = [
+  {
+    event: "Stop",
+    script: "run-stop-guard.sh",
+    timeout: 15,
+    statusMessage: "Checking the pipeline run is not left mid-phase...",
+  },
+  {
+    event: "PreToolUse",
+    matcher: "mcp__.*[Ff]igma.*",
+    script: "run-scope-guard.sh",
+    timeout: 10,
+    statusMessage: "Checking the Figma call against the run's phase...",
+  },
+  {
+    event: "PreToolUse",
+    matcher: AGENT_GUARD_FILE_MATCHER,
+    script: "run-scope-guard.sh",
+    timeout: 10,
+    statusMessage: "Checking the edit is inside the run's worktree...",
+  },
+];
+
+/**
+ * The record of which RUN_HOOKS an install has registered, under ~/.claude. A
+ * key in it whose hook is no longer in settings.json was removed by the user,
+ * and the next install leaves it removed. uninstall.mjs deletes the file.
+ */
+export const HOOK_MANIFEST = "multi-agent-hook-manifest.json";
+
+/** event|matcher|script, the identity of one RUN_HOOKS entry. */
+export const hookKey = (r) => `${r.event}|${r.matcher || ""}|${r.script}`;
+
+function readHookManifest(path) {
+  try {
+    const doc = JSON.parse(readFileSync(path, "utf-8"));
+    return new Set(Array.isArray(doc?.registered) ? doc.registered : []);
+  } catch {
+    return new Set();
+  }
+}
+
+/** True when an entry of the same event and matcher already runs the script. */
+export function hasHook(hooks, r) {
+  const groups = Array.isArray(hooks?.[r.event]) ? hooks[r.event] : [];
+  return groups.some(
+    (g) =>
+      (g?.matcher || "") === (r.matcher || "") &&
+      Array.isArray(g.hooks) &&
+      g.hooks.some((h) => typeof h?.command === "string" && h.command.includes(r.script)),
+  );
+}
+
+/**
+ * Add one pipeline hook unless an entry of the same event and matcher already
+ * runs its script. Returns true when it changed `hooks`.
+ *
+ * @param {object} hooks  settings.hooks
+ * @param {{event: string, matcher?: string, script: string, timeout: number, statusMessage: string}} r
+ */
+export function ensureHook(hooks, r) {
+  if (!Array.isArray(hooks[r.event])) hooks[r.event] = [];
+  const groups = hooks[r.event];
+  if (hasHook(hooks, r)) return false;
+  const hook = {
+    type: "command",
+    command: pipelineHookCommand(r.script),
+    timeout: r.timeout,
+    statusMessage: r.statusMessage,
+  };
+  // Joined to a group of the same matcher when there is one, so a file edit
+  // shows one group with both guards rather than two groups.
+  const same = groups.find(
+    (g) => (g?.matcher || "") === (r.matcher || "") && Array.isArray(g.hooks),
+  );
+  if (same) same.hooks.push(hook);
+  else groups.push(r.matcher ? { matcher: r.matcher, hooks: [hook] } : { hooks: [hook] });
+  return true;
+}
+
 export function configureSettings(home) {
   console.log("  [Claude Code] Configuring hooks + context management...");
   const SETTINGS_PATH = join(home, ".claude", "settings.json");
@@ -942,6 +1038,26 @@ export function configureSettings(home) {
       settingsChanged = true;
     }
 
+    const manifestPath = join(home, ".claude", HOOK_MANIFEST);
+    const manifest = readHookManifest(manifestPath);
+    let manifestChanged = false;
+    for (const r of RUN_HOOKS) {
+      const key = hookKey(r);
+      const had = manifest.has(key);
+      if (hasHook(settings.hooks, r)) {
+        if (!had) {
+          manifest.add(key);
+          manifestChanged = true;
+        }
+        continue;
+      }
+      // Registered by an earlier install and gone now: the user removed it.
+      if (had) continue;
+      ensureHook(settings.hooks, r);
+      manifest.add(key);
+      settingsChanged = true;
+      manifestChanged = true;
+    }
     if (collapseDuplicateHooks(settings.hooks)) settingsChanged = true;
 
     if (settingsChanged && isDryRun()) {
@@ -953,6 +1069,11 @@ export function configureSettings(home) {
     } else {
       console.log("    -> Hooks + env already configured");
     }
+    // After settings.json, so a failed write never records hooks as
+    // registered and the next install still adds them.
+    if (manifestChanged && !isDryRun()) {
+      writeFile(manifestPath, `${JSON.stringify({ registered: [...manifest].sort() }, null, 2)}\n`);
+    }
   } catch (e) {
     console.log(`    -> Warning: Could not configure settings.json: ${e.message}`);
   }

package/install/codex.mjs

@@ -209,6 +209,7 @@ export function installCodex(ctx) {
   const CODEX_SCRIPTS = join(CODEX_DIR, "scripts");
   const CODEX_LIB = join(CODEX_DIR, "lib");
   const CODEX_SCHEMAS = join(CODEX_DIR, "schemas");
+  const CODEX_OFFICE = join(CODEX_DIR, "office");
   const CODEX_TEMPLATES = join(CODEX_DIR, "templates");
   const CODEX_RULES = join(CODEX_DIR, "rules");
   const CODEX_SKILL_REFS = join(CODEX_MA_REFS, "skills");
@@ -224,6 +225,7 @@ export function installCodex(ctx) {
   installScripts(pipelineSrc, CODEX_SCRIPTS, useSymlinks);
   installTree("lib", pipelineSrc, CODEX_LIB, useSymlinks);
   installTree("schemas", pipelineSrc, CODEX_SCHEMAS, useSymlinks);
+  installTree("office", pipelineSrc, CODEX_OFFICE, useSymlinks);
   installTree("rules", pipelineSrc, CODEX_RULES, useSymlinks);
   installTemplates(pipelineSrc, CODEX_TEMPLATES, useSymlinks);
   writeAgentsMd(join(CODEX_DIR, "AGENTS.md"));

package/install/copilot.mjs

@@ -61,6 +61,7 @@ export function installCopilot(ctx) {
   const COPILOT_AGENTS = join(COPILOT_DIR, "agents");
   const COPILOT_SKILLS = join(COPILOT_DIR, "skills");
   const COPILOT_SCHEMAS = join(COPILOT_DIR, "schemas");
+  const COPILOT_OFFICE = join(COPILOT_DIR, "office");
   const COPILOT_LIB = join(COPILOT_DIR, "lib");
   const COPILOT_RULES = join(COPILOT_DIR, "rules");
   const COPILOT_TEMPLATES = join(COPILOT_DIR, "templates");
@@ -72,6 +73,7 @@ export function installCopilot(ctx) {
   installScripts(pipelineSrc, COPILOT_SCRIPTS, useSymlinks);
   installAgents(pipelineSrc, COPILOT_AGENTS, useSymlinks);
   installSchemas(pipelineSrc, COPILOT_SCHEMAS, useSymlinks);
+  installOffice(pipelineSrc, COPILOT_OFFICE, useSymlinks);
   installLib(pipelineSrc, COPILOT_LIB, useSymlinks);
   installRules(pipelineSrc, COPILOT_RULES, useSymlinks);
   installTemplates(pipelineSrc, COPILOT_TEMPLATES, useSymlinks);
@@ -263,6 +265,17 @@ function installSchemas(pipelineSrc, dest, useSymlinks) {
   console.log(`    -> ${countFiles(schemasSrc)} files copied to ${dest}`);
 }
 
+/** The office panel page, served from ../office beside the scripts directory. */
+function installOffice(pipelineSrc, dest, useSymlinks) {
+  console.log("  [Copilot CLI] Installing the office panel page...");
+  const officeSrc = join(pipelineSrc, "office");
+  if (!existsSync(officeSrc)) return;
+  if (!useSymlinks && ensureRealDir(dest) === null) return;
+  wipeDir(dest);
+  copyDir(officeSrc, dest, { useSymlinks });
+  console.log(`    -> ${countFiles(officeSrc)} files copied to ${dest}`);
+}
+
 function installTemplates(pipelineSrc, dest, useSymlinks) {
   // Only install/claude.mjs used to lay this tree down, so a Copilot-only or
   // Codex-only machine had no ~/.claude/templates - and autopilot-on reads the

package/install/templates/claude-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. `install` registers the pre-commit and agent-guard gates itself (install/claude.mjs configureSettings); /multi-agent:setup offers to merge the rest of this block. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic PreToolUse gates real (exit 2 blocks the tool call). A PreToolUse matcher is a regex over the TOOL NAME, so each gate registers on a tool name and reads the command from its stdin payload. Three PreToolUse gates ship here: (1) pre-commit-check.sh on Bash, which acts only on a `git commit` and blocks a secret in the staged diff; (2) agent-guard.sh on Bash, on Edit|Write|NotebookEdit, and on WebFetch plus every multi-agent-toolkit tool (WebFetch|mcp__multi-agent-toolkit__.*). Always, it blocks AI/assistant attribution in a commit message and a force-push, delete or mirror push to a protected branch (main/master/develop), including one inside a subshell or a `bash -c` / `eval` line. With MULTI_AGENT_UNATTENDED=1 in the hook's environment it also applies the unattended policy: no push, PR or tracker write, no Keychain read, no fetch outside the host allowlist (curl, WebFetch, the toolkit's web tools, agent_run_steps and open_url), no package install, and no write into a protected path (features/unattended-security.md); (3) check-read-size.sh on Read|Bash, which inspects Read plus the shell commands that read a file whole (cat/head/tail/sed), returns immediately for everything else, and routes an oversized read to a cheap worker instead of the caller's own rung; it is inert until `prefs.global.bulkRead.mode` is set to observe or enforce. Failure behaviour: pre-commit-check.sh and check-read-size.sh fail open on an internal error. agent-guard.sh fails open when attended, so a guard bug cannot break a legitimate tool call, and fails closed under MULTI_AGENT_UNATTENDED=1, where nobody is there to notice a gap. None of the three executes the inspected command, and none needs run-specific arguments. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. Three capture hooks ship alongside them and block nothing: (4) SessionEnd runs capture-flush.sh --if-stale, which writes a run's triage findings and durable learnings into the per-repo stores when the run ended before Phase 5, where those writes otherwise happen; the same hook runs note-session.sh, which records the mechanical shape of a session outside the pipeline (tools used, commands that failed, calls the user refused). (5) PreCompact runs capture-flush.sh without --if-stale: a compaction summarizes the conversation mid-phase, so it is the moment unflushed findings are at risk, and both writes are idempotent, so a finished run costs two no-op writes. The staleness test exists only so a session exit does not re-flush a run that already finished. (6) SessionStart runs capture-resume.sh, which prints at most two lines: an unfinished run and how to resume it, and a stale pipeline-observation queue. No capture hook calls a model or reads a payload - note-session.sh keeps a command's first word and an exit code, never an argument or any output - and all exit 0 on every path, because a hook that fails a session over bookkeeping costs more than the bookkeeping. One PostToolUse hook ships as well and blocks nothing: (7) edit-syntax-gate.sh on Edit|Write|MultiEdit parses the file the edit just wrote (swiftc -parse, node --check, py_compile into a temp dir, JSON.parse, bash -n; Kotlin skipped) under a 2 s deadline and, when it no longer parses, hands the model the error as PostToolUse additionalContext; it exits 0 on every path, stays silent when a parser is missing or slow, and is inert until `prefs.global.editSyntaxGate.enabled` is true. These registrations are Claude Code's. On Codex only the syntax gate is offered, from codex-hooks.json through host-hooks.mjs; Copilot CLI gets none, since as of 1.0.45 it discards postToolUse output; the other gates are Claude Code only. multi-agent:setup offers to merge this block.",
+  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. `install` registers the pre-commit and agent-guard gates and the run-scoped run-stop-guard / run-scope-guard hooks itself (install/claude.mjs configureSettings, RUN_HOOKS); /multi-agent:setup offers to merge the rest of this block. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic PreToolUse gates real (exit 2 blocks the tool call). A PreToolUse matcher is a regex over the TOOL NAME, so each gate registers on a tool name and reads the command from its stdin payload. Three PreToolUse gates ship here: (1) pre-commit-check.sh on Bash, which acts only on a `git commit` and blocks a secret in the staged diff; (2) agent-guard.sh on Bash, on Edit|Write|NotebookEdit, and on WebFetch plus every multi-agent-toolkit tool (WebFetch|mcp__multi-agent-toolkit__.*). Always, it blocks AI/assistant attribution in a commit message and a force-push, delete or mirror push to a protected branch (main/master/develop), including one inside a subshell or a `bash -c` / `eval` line. With MULTI_AGENT_UNATTENDED=1 in the hook's environment it also applies the unattended policy: no push, PR or tracker write, no Keychain read, no fetch outside the host allowlist (curl, WebFetch, the toolkit's web tools, agent_run_steps and open_url), no package install, and no write into a protected path (features/unattended-security.md); (3) check-read-size.sh on Read|Bash, which inspects Read plus the shell commands that read a file whole (cat/head/tail/sed), returns immediately for everything else, and routes an oversized read to a cheap worker instead of the caller's own rung; it is inert until `prefs.global.bulkRead.mode` is set to observe or enforce. Failure behaviour: pre-commit-check.sh and check-read-size.sh fail open on an internal error. agent-guard.sh fails open when attended, so a guard bug cannot break a legitimate tool call, and fails closed under MULTI_AGENT_UNATTENDED=1, where nobody is there to notice a gap. None of the three executes the inspected command, and none needs run-specific arguments. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. Three capture hooks ship alongside them and block nothing: (4) SessionEnd runs capture-flush.sh --if-stale, which writes a run's triage findings and durable learnings into the per-repo stores when the run ended before Phase 5, where those writes otherwise happen; the same hook runs note-session.sh, which records the mechanical shape of a session outside the pipeline (tools used, commands that failed, calls the user refused). (5) PreCompact runs capture-flush.sh without --if-stale: a compaction summarizes the conversation mid-phase, so it is the moment unflushed findings are at risk, and both writes are idempotent, so a finished run costs two no-op writes. The staleness test exists only so a session exit does not re-flush a run that already finished. (6) SessionStart runs capture-resume.sh, which prints at most two lines: an unfinished run and how to resume it, and a stale pipeline-observation queue. No capture hook calls a model or reads a payload - note-session.sh keeps a command's first word and an exit code, never an argument or any output - and all exit 0 on every path, because a hook that fails a session over bookkeeping costs more than the bookkeeping. A run-scoped PreToolUse gate ships too: (2b) run-scope-guard.sh on every Figma MCP tool (mcp__.*[Ff]igma.*) denies a Figma call above phases.json thresholds.mcpAllowedThroughPhase for the run bound to the session, unless the run is in analysis mode, and records each allowed call into telemetry.mcpCalls[]; on Edit|Write|NotebookEdit the same script warns, attended only, when the target is outside the bound run's worktree (additionalContext for the model, systemMessage for the user; the call proceeds). Outside a run it is silent, and it fails open. One PostToolUse hook ships as well and blocks nothing: (7) edit-syntax-gate.sh on Edit|Write|MultiEdit parses the file the edit just wrote (swiftc -parse, node --check, py_compile into a temp dir, JSON.parse, bash -n; Kotlin skipped) under a 2 s deadline and, when it no longer parses, hands the model the error as PostToolUse additionalContext; it exits 0 on every path, stays silent when a parser is missing or slow, and is inert until `prefs.global.editSyntaxGate.enabled` is true. One Stop hook ships as well: (8) run-stop-guard.sh answers {\"decision\":\"block\"} when the session driving an active pipeline run (bound through agent-state.json sessionId or hostSessionId, never by a worktree match) tries to stop while the run is in_progress below its mode's last phase with no haltReason or waitingFor; the reason says to finish the current phase, record the wait, or record a halt. A turn that ends on a question to the user, a session with background tasks or crons, and prefs.global.stopGuard.enabled false are never held, and SubagentStop is not registered: a subagent's stop is the dispatching session's business. After three consecutive blocks it records the halt itself (status paused, haltReason <phase>:stop-guard), which write-state clears when the run advances a phase. It never blocks outside a run and fails open, with a line in <log root>/hook-failures.log, on any error. These registrations are Claude Code's; README \"Hooks per host\" lists which have no equivalent elsewhere. On Codex only the syntax gate is offered, from codex-hooks.json through host-hooks.mjs; Copilot CLI gets none, since as of 1.0.45 it discards postToolUse output; the other gates are Claude Code only. multi-agent:setup offers to merge this block.",
   "hooks": {
     "PreToolUse": [
       {
@@ -27,6 +27,12 @@
             "command": "bash \"$HOME/.claude/scripts/agent-guard.sh\"",
             "timeout": 10,
             "statusMessage": "Checking the edit target..."
+          },
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.claude/scripts/run-scope-guard.sh\"",
+            "timeout": 10,
+            "statusMessage": "Checking the edit is inside the run's worktree..."
           }
         ]
       },
@@ -51,6 +57,17 @@
             "statusMessage": "Checking read size..."
           }
         ]
+      },
+      {
+        "matcher": "mcp__.*[Ff]igma.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.claude/scripts/run-scope-guard.sh\"",
+            "timeout": 10,
+            "statusMessage": "Checking the Figma call against the run's phase..."
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -108,6 +125,18 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.claude/scripts/run-stop-guard.sh\"",
+            "timeout": 15,
+            "statusMessage": "Checking the pipeline run is not left mid-phase..."
+          }
+        ]
+      }
     ]
   }
 }