@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/install/index.mjs

@@ -20,6 +20,7 @@ import { installCopilot } from "./copilot.mjs";
 import { installCodex } from "./codex.mjs";
 import { setDryRun, writeFile } from "./_common.mjs";
 import { sendInstallTelemetry } from "./_telemetry.mjs";
+import { applyUnattendedProfile, describeUnattendedProfile } from "./_unattended-profile.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Repository root (one level above install/). */
@@ -63,6 +64,7 @@ export async function runInstall(argv) {
     "--index-only",
     "--dry-run",
     "--prune-external",
+    "--unattended",
   ];
   const KNOWN_PREFIXES = ["--platform="];
   const unknown = flags.filter(
@@ -91,6 +93,7 @@ export async function runInstall(argv) {
   const useSymlinks = flags.includes("--link");
   const indexOnly = flags.includes("--index-only");
   const pruneExternal = flags.includes("--prune-external");
+  const unattended = flags.includes("--unattended");
   const platformFlag = parsePlatformFlag(flags);
 
   const installerCtx = {
@@ -117,12 +120,15 @@ export async function runInstall(argv) {
   writeVersionMarkers({ home: HOME, forClaude, forCopilot, forCodex });
 
   if (dryRun) {
+    if (unattended) applyUnattended({ home: HOME, forClaude, dryRun: true });
     console.log("");
     console.log("  Dry-run complete - nothing was written. Re-run without --dry-run to install.");
     console.log("");
     return;
   }
 
+  if (unattended) applyUnattended({ home: HOME, forClaude });
+
   printSummary({ forClaude, forCopilot, forCodex });
 
   // Fire-and-forget; install is already done.
@@ -135,6 +141,48 @@ export async function runInstall(argv) {
  *
  * @param {{home: string, forClaude: boolean, forCopilot: boolean, forCodex?: boolean}} opts
  */
+/**
+ * Print the unattended permission profile, then apply it. Printing first is the
+ * contract: an installer that widens a permission set has to say what it is
+ * about to allow while the person can still stop it, not report it afterwards.
+ *
+ * Claude Code only. The profile is a ~/.claude/settings.json shape, and writing
+ * it for a host that does not read that file would be a line in a report that
+ * nothing acts on.
+ *
+ * @param {{home:string, forClaude:boolean, dryRun?:boolean}} opts
+ */
+function applyUnattended({ home, forClaude, dryRun = false }) {
+  if (!forClaude) {
+    console.log("");
+    console.log("  --unattended applies to Claude Code only; nothing written.");
+    return;
+  }
+  let existing = [];
+  try {
+    const settings = JSON.parse(readFileSync(join(home, ".claude", "settings.json"), "utf-8"));
+    existing = (settings?.permissions?.allow ?? []).map(String);
+  } catch {
+    // No settings file yet, or one that does not parse. Either way there is
+    // nothing to mark as "already there"; applyUnattendedProfile decides what
+    // to do about the unparseable case.
+  }
+  console.log("");
+  console.log(describeUnattendedProfile(existing));
+  try {
+    const res = applyUnattendedProfile({ home, dryRun });
+    console.log("");
+    if (dryRun) console.log(`  (dry-run) would add ${res.added.length} entr(ies) to ${res.path}`);
+    else if (!res.added.length) console.log(`  nothing to add - ${res.path} already covers it`);
+    else console.log(`  added ${res.added.join(", ")} to ${res.path}`);
+  } catch (err) {
+    // A settings file we cannot parse is the user's, and rewriting it would
+    // lose whatever is in there. Refusing loudly beats a silent overwrite.
+    console.log("");
+    console.log(`  permission profile NOT written: ${err.message}`);
+  }
+}
+
 export function writeVersionMarkers({ home, forClaude, forCopilot, forCodex }) {
   let version;
   try {

package/install/templates/claude-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic, OS-enforced PreToolUse gates real (exit 2 blocks the tool call) rather than prompt-level hopes. Three PreToolUse gates ship here: (1) a staged-diff secret scan on git commit (pre-commit-check.sh); (2) an agent-guard on git commit + git push (agent-guard.sh) that blocks AI/assistant attribution in commit messages and force-push to a protected branch (main/master/develop); (3) a read-size gate on Read and Bash (check-read-size.sh), which inspects Read plus the shell commands that read a file whole (cat/head/tail/sed) and returns immediately for everything else, which routes an oversized read to a cheap worker instead of the caller's own rung. The first two inspect what a run WRITES; the third inspects what it pays to READ, and it is inert until `prefs.global.bulkRead.mode` is set to observe or enforce - so merging this block changes nothing until you opt in. All three are self-contained, fail-open on internal error, never execute the inspected command, and need no run-specific arguments, which is why they are naturally PreToolUse hooks. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. Two capture hooks ship alongside them, and they are the reason a killed run no longer loses what it learned: (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 never reached Phase 7 - previously every persistent write lived in Phase 7, the phase a run is LEAST likely to reach; the same hook runs note-session.sh, which records the mechanical shape of a NON-pipeline session (tools used, commands that failed, calls the user refused) so work done outside a run stops vanishing. (5) 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. Neither capture hook calls a model, neither reads a payload - note-session.sh keeps a command's first word and an exit code, never an argument or any output - and both exit 0 on every path, because a hook that fails a session over bookkeeping is worse than the bookkeeping it protects. multi-agent:setup offers to merge this block.",
+  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic, OS-enforced PreToolUse gates real (exit 2 blocks the tool call) rather than prompt-level hopes. Three PreToolUse gates ship here: (1) a staged-diff secret scan on git commit (pre-commit-check.sh); (2) an agent-guard on git commit + git push (agent-guard.sh) that blocks AI/assistant attribution in commit messages and force-push to a protected branch (main/master/develop); (3) a read-size gate on Read and Bash (check-read-size.sh), which inspects Read plus the shell commands that read a file whole (cat/head/tail/sed) and returns immediately for everything else, which routes an oversized read to a cheap worker instead of the caller's own rung. The first two inspect what a run WRITES; the third inspects what it pays to READ, and it is inert until `prefs.global.bulkRead.mode` is set to observe or enforce - so merging this block changes nothing until you opt in. All three are self-contained, fail-open on internal error, never execute the inspected command, and need no run-specific arguments, which is why they are naturally PreToolUse hooks. 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 they are the reason a killed run no longer loses what it learned: (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 never reached Phase 7 - previously every persistent write lived in Phase 7, the phase a run is LEAST likely to reach; the same hook runs note-session.sh, which records the mechanical shape of a NON-pipeline session (tools used, commands that failed, calls the user refused) so work done outside a run stops vanishing. (5) PreCompact runs capture-flush.sh - WITHOUT --if-stale, because the staleness test exists so a session exit does not re-flush a run that already finished, while a compaction is the moment un-flushed findings are actually at risk and both writes are idempotent, so the finished case costs two no-op writes. A compaction summarizes the conversation mid-phase: a long Phase 3 or Phase 4 can lose what it established before SessionEnd ever fires, which is the same failure that put the SessionEnd hook here one level down. (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, none 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 is worse than the bookkeeping it protects. multi-agent:setup offers to merge this block.",
   "hooks": {
     "PreToolUse": [
       {
@@ -42,6 +42,18 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $HOME/.claude/scripts/capture-flush.sh --quiet",
+            "timeout": 20,
+            "statusMessage": "Persisting what this run learned before compaction..."
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [