@dev-loops/core 1.0.2 → 1.0.4-pre.0

package/src/claude/hook-decisions.mjs

@@ -12,14 +12,15 @@
 import { resolveRunId } from "../loop/run-context.mjs";
 import { isUnderWorktreePath } from "../loop/worktree-guard.mjs";
 import {
+  deriveInManagedRepo,
   commandContainsGhPrReady,
   commandContainsGhPrMerge,
   commandContainsGhPrCreate,
   extractPrNumberFromGhPrReadyAnywhere,
-  extractRepoFlagFromGhPrReadyAnywhere,
   extractPrNumberFromGhPrMergeAnywhere,
-  extractRepoFlagFromGhPrMergeAnywhere,
   extractRepoFlagsFromGhPrCreateSegments,
+  extractRepoFlagsFromGhPrMergeSegments,
+  extractRepoFlagsFromGhPrReadySegments,
   commandContainsRawExternalWrite,
   extractRepoFlagsFromExternalWriteSegments,
   commandContainsGitStash,
@@ -31,7 +32,7 @@ import {
   commandContainsCopilotSummonComment,
   commandContainsDetachedWaitTool,
   commandContainsInlineInterpreter,
-  TARGET_REPO_SLUG,
+  commandContainsCodeVerificationEntrypoint,
 } from "../loop/bash-command-classify.mjs";
 
 /**
@@ -61,6 +62,24 @@ function commandContainsEvidenceWrite(command) {
  */
 export const DEV_LOOP_AGENT_TYPE = "dev-loop";
 
+/**
+ * Normalize a Claude `agent_type` hook-payload value that may be PLUGIN-NAMESPACED
+ * (`<plugin-name>:<agent-name>`, e.g. `dev-loops:dev-loop`) to the bare agent name the coordinator
+ * deciders compare against `DEV_LOOP_AGENT_TYPE`. Returns the substring after the last `:` when
+ * present, else `agentType` unchanged (including `null`/non-string, passed through as-is).
+ *
+ * Applied in the coordinator-scoped deciders (`decideBashGate`, `decideCoordinatorWriteGuard`).
+ * Deliberately NOT applied in `decideWriteGuard` — its main-agent allow-set boundary is covered by
+ * the `DEVLOOPS_RUN_ID` run-id check first, and broadening that decider's comparison is out of
+ * scope for the coordinator→worker delegation boundary.
+ * @param {string|null|undefined} agentType @returns {string|null|undefined}
+ */
+export function normalizeAgentType(agentType) {
+  if (typeof agentType !== "string") return agentType;
+  const idx = agentType.lastIndexOf(":");
+  return idx === -1 ? agentType : agentType.slice(idx + 1);
+}
+
 /**
  * Decide whether a PreToolUse Bash command must be blocked by a dev-loop gate boundary.
  *
@@ -68,8 +87,9 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  *   - `gh pr create` — blocked outright; PR creation must flow through the canonical wrapper
  *     (`scripts/github/create-pr.mjs` / `dev-loops pr create`), which always drafts and self-assigns.
  *   - `gh pr ready` — blocked without clean draft_gate evidence.
- *   - `gh pr merge` — blocked without full pre-merge gate evidence (clean current-head draft_gate +
- *     pre_approval_gate).
+ *   - `gh pr merge` — blocked outright; use scripts/github/merge-pr.mjs. Its gate evidence check
+ *     requires a clean draft_gate transition record + current-head pre_approval_gate
+ *     (GATE-COMMENT-DRAFT-REQUIREMENTS in skills/docs/gate-review-comment-contract.md).
  *   - raw `gh issue create` / `gh issue comment` / `gh issue edit` / `gh pr comment` — blocked ONLY
  *     from a SUBAGENT context (`agentType` non-null) on the target repo. Sanctioned external writes
  *     flow through node wrappers; the MAIN AGENT / operator (agentType null) retains direct access.
@@ -79,6 +99,11 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  * @param {Object} params
  * @param {string} params.command - The Bash command string.
  * @param {string|null} [params.repoSlug] - Resolved owner/name of the cwd repo (null if unknown).
+ * @param {string|null} [params.managedRepoSlug] - Resolved owner/name of the dev-loops-managed
+ *   repo (the repo `inManagedContext` refers to), or null when the identity can't be resolved.
+ * @param {boolean} [params.inManagedContext] - Whether the current repo is dev-loops-managed (a
+ *   `.devloops` config exists at its root). Replaces the old hardcoded-slug `TARGET_REPO_SLUG`
+ *   comparison so the guard suite applies in any managed consumer repo, not only mfittko/dev-loops.
  * @param {boolean} [params.gatePassed] - Whether the relevant gate evidence exists for the PR.
  * @param {string|null} [params.gateError] - Error detail when the gate guard could not run.
  * @param {string|null} [params.agentType] - Claude `agent_type` from the hook payload; non-null
@@ -87,21 +112,58 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  *   (`resolveHumanMergeOnly`); when true, `gh pr merge` is refused actor-independently
  *   (STOP-HUMAN-MERGE-001), because the main agent is the actor that performs GitHub writes and a
  *   subagent-only deny would enforce nothing.
+ * @param {boolean} [params.enforceCoordinator] - Strict mode for the COORDINATOR-VERIFY-DELEGATION
+ *   boundary, derived by the hook from `DEVLOOPS_COORDINATOR_READONLY=1` — the SAME flag that
+ *   gates `decideCoordinatorWriteGuard`. Default fail-open (mirrors that boundary).
  * @returns {HookDecision}
  */
-export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null, agentType = null, humanMergeOnly = false }) {
+export function decideBashGate({
+  command,
+  repoSlug = null,
+  managedRepoSlug = null,
+  inManagedContext = false,
+  gatePassed = false,
+  gateError = null,
+  agentType = null,
+  humanMergeOnly = false,
+  enforceCoordinator = false,
+}) {
   if (typeof command !== "string") {
     return ALLOW;
   }
+
+  // COORDINATOR-VERIFY-DELEGATION: a known code-verification/build entrypoint (bun run
+  // verify/test, vitest, npm test/run test/run build, ...) run inline by the dev-loop COORDINATOR
+  // itself (agent_type "dev-loop"). WORKER subagents (developer/fixer/quality/review) may run these
+  // freely — only the coordinator is scoped out, mirroring `decideCoordinatorWriteGuard`'s
+  // agent_type discriminator. Opt-in via the same `DEVLOOPS_COORDINATOR_READONLY=1` flag as the
+  // write-guard boundary; default fail-open. Not scoped to `inManagedRepo` — this is a local
+  // command-invocation boundary (which binary ran), not a GitHub-repo-targeting one.
+  if (enforceCoordinator && normalizeAgentType(agentType) === DEV_LOOP_AGENT_TYPE && commandContainsCodeVerificationEntrypoint(command)) {
+    return {
+      decision: "deny",
+      reason:
+        "COORDINATOR-VERIFY-DELEGATION: the dev-loop coordinator must not run code-verification/build " +
+        "commands inline. Delegate the verification run to a fresh worker subagent (developer/fixer/" +
+        "quality/review), which reports back a compact pass/fail plus any failing-test names — or, when " +
+        "checking a pushed commit, prefer CI's structured conclusion (`gh pr checks` / " +
+        "scripts/github/detect-checkpoint-evidence.mjs) over a local run. See skills/docs/main-agent-contract.md.",
+    };
+  }
   // Normalize (trim + case-fold) so a divergent slug (surrounding whitespace, casing) does not
-  // silently fail OPEN and disable every guard that depends on inTargetRepo.
-  const inTargetRepo = (repoSlug ?? "").trim().toLowerCase() === TARGET_REPO_SLUG.trim().toLowerCase();
+  // silently fail OPEN. A repo is dev-loops-managed when inManagedContext is true (a .devloops
+  // config exists at its root); the managed slug is that repo's resolved identity, which may be
+  // unresolvable (null). FAIL CLOSED: inside a managed context whose identity can't be resolved,
+  // every guard below still applies (inManagedRepo stays true) rather than silently allowing
+  // everything — an unresolvable identity must never disable the guard suite.
+  const managedSlug = (managedRepoSlug ?? "").trim().toLowerCase() || null;
+  const inManagedRepo = deriveInManagedRepo({ inManagedContext, managedRepoSlug, repoSlug });
 
   // OPS-NO-INLINE-INTERPRETER: inline interpreters (`node -e`/`--eval`/`-p`, `python3 -c`,
   // heredocs fed to node/python) are barred actor-independently on the target repo — the rule bars
   // "Coordinator and agent flows"; sanctioned output parsing uses `--jq`/`--silent`, never an
   // inline interpreter.
-  if (inTargetRepo && commandContainsInlineInterpreter(command)) {
+  if (inManagedRepo && commandContainsInlineInterpreter(command)) {
     return {
       decision: "deny",
       reason:
@@ -111,12 +173,35 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     };
   }
 
+  // COPILOT-FOLLOWUP-WAIT-TOOLS: banned detached/polling wait wrappers. Actor-independent: the
+  // coordinator/main agent — not subagents only — is the actor that leaves backgrounded
+  // `until`/`while … sleep … done` poll loops and bare-`&` backgrounded probe shells orphaned
+  // under the Claude Code harness (no async wake to join them), so the gate must deny its
+  // backgrounding too. Evaluated HERE, before the `gh pr ready`/`merge`/`create` classification,
+  // so a compound command that pairs a lifecycle verb with a backgrounded wait
+  // (`gh pr create --repo other/x && node …/probe-copilot-review.mjs … &`) cannot short-circuit
+  // past it via the create/ready ALLOW paths. The sanctioned wait is always a bounded FOREGROUND
+  // inline probe (`probe-copilot-review.mjs` / `wait-pr-checks.mjs` with an explicit
+  // --timeout/--timeout-ms; `gh run watch`; the watch-cycle CLIs).
+  if (inManagedRepo && commandContainsDetachedWaitTool(command)) {
+    return {
+      decision: "deny",
+      reason:
+        "COPILOT-FOLLOWUP-WAIT-TOOLS: wait only through a bounded FOREGROUND probe (scripts/github/" +
+        "probe-copilot-review.mjs or scripts/github/wait-pr-checks.mjs with an explicit --timeout/" +
+        "--timeout-ms; scripts/loop/detect-copilot-loop-state.mjs one-shot; dev-loops loop watch-cycle; " +
+        "gh run watch) — nohup/disown/tmux/screen detach, while-sleep-poll loops, and bare-`&` " +
+        "backgrounding of a probe/wait script are barred for the coordinator and every subagent (a " +
+        "backgrounded wait orphans under Claude Code, which has no async wake to join it).",
+    };
+  }
+
   // SUBISSUE-NO-ADHOC-BYPASS: ad-hoc `gh api` writes to the target repo's sub-issue endpoints.
   // Actor-independent (no reserved direct path). Gated on the target repo: the absolute slug-embedded
   // form identifies the target repo; the bare relative form (`gh api issues/5/sub_issues`) resolves
   // against the cwd repo, so it is in scope only when running in the target repo (mirrors the
   // explicit-`--repo`/cwd-target posture).
-  if (inTargetRepo && commandContainsSubIssueAdHocBypass(command)) {
+  if (inManagedRepo && commandContainsSubIssueAdHocBypass(command, managedSlug)) {
     return {
       decision: "deny",
       reason:
@@ -129,7 +214,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // to pulls/<n>/comments/<m>/replies, or a `gh api graphql` resolveReviewThread mutation (the Rest
   // path names the target repo; the graphql form has no path-host repo, so it is scoped to the cwd
   // repo). Actor-independent: reply through reply-resolve-review-thread(s).mjs.
-  if (inTargetRepo && (commandContainsReplyResolveBypass(command) || commandContainsGraphqlResolveReviewThread(command))) {
+  if (inManagedRepo && (commandContainsReplyResolveBypass(command, managedSlug) || commandContainsGraphqlResolveReviewThread(command))) {
     return {
       decision: "deny",
       reason:
@@ -142,7 +227,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY: ad-hoc Copilot review requests — raw `gh api` writes
   // to pulls/<n>/requested_reviewers, or a bare `/copilot` / `/copilot re-review` comment summon on the
   // target repo. Actor-independent: request Copilot via scripts/github/request-copilot-review.mjs.
-  if (inTargetRepo && (commandContainsCopilotRequestBypass(command) || commandContainsCopilotSummonComment(command))) {
+  if (inManagedRepo && (commandContainsCopilotRequestBypass(command, managedSlug) || commandContainsCopilotSummonComment(command))) {
     return {
       decision: "deny",
       reason:
@@ -156,7 +241,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // `.git` directory — a stash from one worktree can pop into another's. Block it outright on the
   // target repo; see skills/docs/worktree-guidance.md#never-git-stash-in-a-shared-git-layout for the
   // stash-free alternative (git diff / a patch file / a scratch checkout).
-  if (commandContainsGitStash(command) && inTargetRepo) {
+  if (commandContainsGitStash(command) && inManagedRepo) {
     return {
       decision: "deny",
       reason:
@@ -169,14 +254,19 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // `gh issue edit`/`gh pr comment` on the target repo from a subagent, so external writes flow through the
   // sanctioned node wrappers. The main-agent/operator path (agentType null) is unaffected.
   if (typeof agentType === "string" && commandContainsRawExternalWrite(command)) {
-    const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
+    // The cwd repo IS the managed/target repo exactly when inManagedRepo.
+    const cwdTargets = inManagedRepo;
     // Scope PER segment, mirroring the `gh pr create` block: in scope when no explicit --repo and
-    // cwd is the target, or an explicit --repo/-R equals the target. An explicit non-target --repo
-    // passes through. DENY if ANY external-write segment is in scope.
+    // cwd is the target, or an explicit --repo/-R equals the managed slug. An explicit repo that is
+    // PROVEN foreign (managedSlug resolves and differs) passes through; otherwise (managedSlug
+    // unresolvable) we cannot prove the explicit repo is foreign, so a managed context fails closed
+    // (in scope). DENY if ANY external-write segment is in scope.
     const anyWriteInScope = extractRepoFlagsFromExternalWriteSegments(command).some((seg) =>
       seg.explicitRepo == null
         ? cwdTargets
-        : seg.explicitRepo.toLowerCase() === TARGET_REPO_SLUG.toLowerCase(),
+        : managedSlug !== null
+          ? seg.explicitRepo.toLowerCase() === managedSlug
+          : inManagedContext,
     );
     if (anyWriteInScope) {
       return {
@@ -202,7 +292,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // refused actor-independently — the main agent is the actor that performs GitHub writes, so only an
   // actor-independent deny enforces the human-merge invariant (an agent-scoped deny would enforce
   // nothing on the main-agent write path).
-  if (humanMergeOnly && isMerge && inTargetRepo) {
+  if (humanMergeOnly && isMerge && inManagedRepo) {
     return {
       decision: "deny",
       reason:
@@ -213,20 +303,9 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   }
 
   if (!isReady && !isMerge && !isCreate) {
-    // COPILOT-FOLLOWUP-WAIT-TOOLS: banned detached/polling wait wrappers. Subagent-only — the
-    // rule is classified `agent` (behavioral guidance for the dev-loop driving agent); the main
-    // agent/operator retains manual wait tooling. The main agent's own sanctioned wait path is still
-    // the deterministic tools.
-    if (typeof agentType === "string" && inTargetRepo && commandContainsDetachedWaitTool(command)) {
-      return {
-        decision: "deny",
-        reason:
-          "COPILOT-FOLLOWUP-WAIT-TOOLS: wait only through deterministic tools (scripts/loop/detect-copilot-" +
-          "loop-state.mjs one-shot, dev-loops loop watch-cycle persistent, scripts/github/wait-pr-checks.mjs, " +
-          "gh run watch) — nohup/disown/tmux/screen detach and while-sleep-poll loops are barred for the " +
-          "dev-loop driving agent.",
-      };
-    }
+    // The detached-wait deny (COPILOT-FOLLOWUP-WAIT-TOOLS) is evaluated earlier — actor-independently
+    // and BEFORE this lifecycle-verb classification — so a compound command pairing a lifecycle verb
+    // with a backgrounded wait cannot short-circuit past it through the create/ready ALLOW paths.
     return ALLOW;
   }
 
@@ -234,16 +313,21 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // exists yet): PR creation must flow through the canonical wrapper, which always drafts and
   // self-assigns. This closes the draft-first hole where raw `gh pr create` opens a ready PR.
   if (isCreate) {
-    const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
+    // The cwd repo IS the managed/target repo exactly when inManagedRepo.
+    const cwdTargets = inManagedRepo;
     // Evaluate scope PER create segment, not just the first: a create is in scope when it
     // explicitly targets the repo, or (with no explicit --repo) the cwd is the repo. An explicit
-    // `--repo <target>` is denied regardless of cwd. DENY if ANY create segment is in
-    // scope — otherwise a leading out-of-scope create (`gh pr create --repo other/repo`) would
-    // short-circuit and shield a later in-scope raw create (`&& gh pr create --fill`).
+    // `--repo <target>` is denied regardless of cwd — unless it is PROVEN foreign (managedSlug
+    // resolves and differs); when managedSlug is unresolvable we cannot prove foreignness, so a
+    // managed context fails closed (in scope). DENY if ANY create segment is in scope — otherwise a
+    // leading out-of-scope create (`gh pr create --repo other/repo`) would short-circuit and shield
+    // a later in-scope raw create (`&& gh pr create --fill`).
     const anyCreateInScope = extractRepoFlagsFromGhPrCreateSegments(command).some((seg) =>
       seg.explicitRepo == null
         ? cwdTargets
-        : seg.explicitRepo.toLowerCase() === TARGET_REPO_SLUG.toLowerCase(),
+        : managedSlug !== null
+          ? seg.explicitRepo.toLowerCase() === managedSlug
+          : inManagedContext,
     );
     if (anyCreateInScope) {
       return {
@@ -262,18 +346,30 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
       return ALLOW;
     }
   }
-  // When both verbs appear in a compound command, apply the stricter merge gate — if it passes,
-  // the draft_gate (a subset of the pre-merge evidence check) is also satisfied.
+  // When both verbs appear in a compound command, the unconditional raw-merge refusal wins.
   const verb = isMerge ? "gh pr merge" : "gh pr ready";
-  // An explicit `--repo other/repo` that is not the target → not our concern, pass through.
-  const explicitRepo = isMerge
-    ? extractRepoFlagFromGhPrMergeAnywhere(command)
-    : extractRepoFlagFromGhPrReadyAnywhere(command);
-  if (explicitRepo && explicitRepo.toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
+  // Pass through only when EVERY gated verb segment is PROVEN foreign (explicit repo, managed slug
+  // resolves, and demonstrably differs). A segment with no explicit repo, or an unresolvable managed
+  // slug, is NOT proven foreign — fail closed (preserves the fail-closed default). Mirrors the
+  // per-segment `.some()` scoping on the create/external-write paths: a proven-foreign FIRST segment
+  // must not shield a later managed segment (`gh pr merge --repo other/x 1 && gh pr merge 2`).
+  const gatedVerbSegments = [
+    ...(isMerge ? extractRepoFlagsFromGhPrMergeSegments(command) : []),
+    ...(isReady ? extractRepoFlagsFromGhPrReadySegments(command) : []),
+  ];
+  const allSegmentsProvenForeign =
+    gatedVerbSegments.length > 0 &&
+    gatedVerbSegments.every(
+      (seg) =>
+        seg.explicitRepo != null &&
+        managedSlug !== null &&
+        seg.explicitRepo.toLowerCase() !== managedSlug,
+    );
+  if (allSegmentsProvenForeign) {
     return ALLOW;
   }
-  // Only gate within the target repo (case-insensitive — callers may pass an un-lowercased slug).
-  if ((repoSlug ?? "").toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
+  // Only gate within the managed repo.
+  if (!inManagedRepo) {
     return ALLOW;
   }
 
@@ -287,31 +383,38 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     };
   }
 
-  if (gateError) {
-    const which = isMerge ? "pre-merge gate" : "draft-gate";
+  // Raw `gh pr merge` is FORBIDDEN outright (RAW-GH-PR-MERGE-BYPASS): the only
+  // sanctioned merge path is the wrapper, which enforces the mandatory approver,
+  // merge class, and fresh-approval checks a bare evidence gate cannot. A
+  // gate-passed raw merge would bypass all of those, so this denies
+  // unconditionally (not only when evidence is missing) and points to the wrapper.
+  // The wrapper's own internal `gh pr merge` is a child_process spawn, never a
+  // Bash tool call, so it is never seen here.
+  if (isMerge) {
+    // This hook evaluates PreToolUse — BEFORE the Bash tool call runs. A compound command that
+    // writes gate evidence (findings-log ledger, checkpoint verdict) and merges in the same call
+    // is blocked here with the write never having executed. Hint the split when the command
+    // carries an evidence-writing invocation alongside the merge.
+    const alsoWritesEvidence = commandContainsEvidenceWrite(command);
     return {
       decision: "deny",
-      reason: `${verb} blocked: ${which} evidence check failed (${gateError}).`,
+      reason:
+        `gh pr merge is forbidden: route the merge through the sanctioned wrapper \`node scripts/github/merge-pr.mjs --repo <owner/name> --pr ${prNumber} --human-approved-by <login>\`, which runs the full precondition set fail-closed (mandatory approver, merge class, fresh approval) — a raw \`gh pr merge\` bypasses those (RAW-GH-PR-MERGE-BYPASS).` +
+        (gateError ? ` (pre-merge gate evidence check also failed: ${gateError})` : "") +
+        (alsoWritesEvidence
+          ? " This command also writes gate evidence, but hooks evaluate before the command runs — never chain an evidence write with the merge."
+          : ""),
     };
   }
 
+  // `gh pr ready` keeps its gate-conditional behavior.
+  if (gateError) {
+    return {
+      decision: "deny",
+      reason: `${verb} blocked: draft-gate evidence check failed (${gateError}).`,
+    };
+  }
   if (!gatePassed) {
-    if (isMerge) {
-      // This hook evaluates PreToolUse — BEFORE the Bash tool call runs. A compound command that
-      // writes gate evidence (findings-log ledger, checkpoint verdict) and merges in the same call
-      // is blocked here with the write never having executed, which looks like the evidence
-      // "vanished". Hint the split when the command carries an evidence-writing invocation
-      // alongside the merge, so the failure is self-explaining instead of looking like data loss.
-      const alsoWritesEvidence = commandContainsEvidenceWrite(command);
-      return {
-        decision: "deny",
-        reason:
-          `gh pr merge blocked: missing pre-merge gate evidence for PR #${prNumber} (need clean current-head draft_gate + pre_approval_gate; inline verdicts are not accepted). Run the dev-loop gates instead of merging directly.` +
-          (alsoWritesEvidence
-            ? " This command also writes gate evidence, but hooks evaluate before the command runs — write the evidence in a separate call, then merge alone."
-            : ""),
-      };
-    }
     return {
       decision: "deny",
       reason: `gh pr ready blocked: no visible clean draft_gate checkpoint verdict comment found for PR #${prNumber}.`,
@@ -362,6 +465,51 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
   };
 }
 
+/**
+ * Decide whether a PreToolUse Write/Edit must be blocked by the coordinator→worker delegation
+ * boundary — the INVERSE of `decideWriteGuard`, one level down. Under the Claude Code
+ * harness the dev-loop agent itself (Claude `agent_type === "dev-loop"`) acts as a delegating
+ * COORDINATOR: it MUST NOT mutate TRACKED repo files directly — that work is delegated to a fresh
+ * WORKER subagent (`developer`/`fixer`/`quality`/`docs`). `agent_type` is the only discriminator:
+ * `DEVLOOPS_RUN_ID` does not distinguish coordinator from worker (the coordinator mints it and
+ * propagates it to the workers it dispatches), so — unlike `decideWriteGuard` — this decider does
+ * not key on run id at all.
+ *
+ * Denies only when ALL of: strict enforcement is on, the target is a tracked repo mutation, AND
+ * the caller's `agent_type` is the coordinator's (`"dev-loop"`). Every other `agent_type` —
+ * including `null` (the Pi main agent / an interactive Claude session with no subagent context,
+ * which is `decideWriteGuard`'s boundary, not this one) and any worker role — is allowed here.
+ * Strict enforcement is opt-in via `enforce` (the hook derives it from
+ * `DEVLOOPS_COORDINATOR_READONLY=1`); default is fail-open, mirroring `decideWriteGuard`'s
+ * adopt-safe precedent so enabling this boundary does not retroactively break a repo's own
+ * interactive Claude Code dev.
+ *
+ * @param {Object} params
+ * @param {string} params.filePath - Target file path.
+ * @param {boolean} params.isRepoMutation - True if inside the repo working tree AND not gitignored.
+ * @param {boolean} [params.enforce] - Strict mode (DEVLOOPS_COORDINATOR_READONLY=1).
+ * @param {string|null} [params.agentType] - Claude `agent_type` from the hook payload, if any.
+ * @returns {HookDecision}
+ */
+export function decideCoordinatorWriteGuard({ filePath, isRepoMutation, enforce = false, agentType = null }) {
+  if (!enforce) {
+    return ALLOW; // strict enforcement not enabled — fail open
+  }
+  if (!isRepoMutation) {
+    return ALLOW; // non-repo or gitignored path (tmp/, the scratchpad, sanctioned ledger paths)
+  }
+  if (normalizeAgentType(agentType) !== DEV_LOOP_AGENT_TYPE) {
+    return ALLOW; // not the coordinator — a worker subagent, or the main agent (the other boundary)
+  }
+  return {
+    decision: "deny",
+    reason:
+      `Coordinator→worker delegation boundary: refusing to mutate repository path "${filePath}" as the ` +
+      "dev-loop coordinator. Delegate this tracked-file edit to a fresh worker subagent (developer/fixer/" +
+      "quality/docs) instead of writing it directly. See skills/docs/main-agent-contract.md.",
+  };
+}
+
 /**
  * Env var that authorizes a deliberate main-checkout mutation while a worktree
  * cycle is active. Reuses the existing default-branch-guard override