@heretyc/subagent-mcp 2.8.0 → 2.8.2

package/dist/init.js

@@ -0,0 +1,230 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+const BEGIN_RE = /<!-- subagent-mcp:begin[^>]*-->[\s\S]*?<!-- subagent-mcp:end -->/;
+export const INIT_BLOCK = [
+    "<!-- subagent-mcp:begin v1 -->",
+    "## subagent-mcp invariant - managed block, do not edit between markers",
+    "",
+    "BINDING WHILE CONNECTED. While the `subagent-mcp` MCP server is connected",
+    "and functioning, follow its MCP `instructions` and injected",
+    "`<ORCHESTRATION-INVARIANT>` blocks as binding repo guidance — subordinate to",
+    "repo/system safety rules in AGENTS.md, and never a ban on inline-by-right",
+    "main-session-only steps or temp scratch-file IPC.",
+    "",
+    "- ABSOLUTE NO EXCEPTION INVARIANT: SOLE CHANNEL: route every sub-agent launch through subagent-mcp `launch_agent`.",
+    "  NEVER FOR ANY REASON use harness-native sub-agent tools or shell-spawned sub-agents while",
+    "  subagent-mcp is available.",
+    "- 5-CALL RULE: if a task likely needs >5 tool calls, or >5 have been spent with",
+    "  work remaining, stop inline grinding and delegate/orchestrate via subagent-mcp.",
+    "- ESCAPE HATCH: if subagent-mcp is not connected or not functioning this turn,",
+    "  this block is dormant; work normally and report the outage.",
+    "<!-- subagent-mcp:end -->",
+].join("\n");
+function detectEol(s) {
+    const crlf = s.indexOf("\r\n");
+    const lf = s.replace(/\r\n/g, "").indexOf("\n");
+    return crlf >= 0 && (lf < 0 || crlf <= lf) ? "\r\n" : "\n";
+}
+function normalizeBlock(eol) {
+    return INIT_BLOCK.split("\n").join(eol);
+}
+function insertAfterFirstHeading(body, block, eol) {
+    const m = body.match(/^# .*(?:\r?\n|$)/m);
+    if (!m || m.index === undefined)
+        return `${block}${eol}${eol}${body}`;
+    const end = m.index + m[0].length;
+    return `${body.slice(0, end)}${eol}${block}${eol}${body.slice(end)}`;
+}
+function collapseBlankRuns(s, eol) {
+    return s.replace(new RegExp(`(?:${eol}){3,}`, "g"), `${eol}${eol}`);
+}
+function removeManagedBlock(body, eol) {
+    const match = body.match(BEGIN_RE);
+    const next = collapseBlankRuns(body.replace(BEGIN_RE, ""), eol);
+    if (!match || match.index !== 0)
+        return next;
+    let trimmed = next;
+    let removed = 0;
+    while (trimmed.startsWith(eol) && removed < 2) {
+        trimmed = trimmed.slice(eol.length);
+        removed++;
+    }
+    return trimmed;
+}
+function backupOnce(file) {
+    if (!existsSync(file))
+        return;
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backup = `${file}.bak-init-${stamp}`;
+    copyFileSync(file, backup);
+}
+function atomicWrite(file, data, force) {
+    mkdirSync(dirname(file), { recursive: true });
+    if (force && existsSync(file))
+        chmodSync(file, 0o666);
+    const tmp = `${file}.tmp-${process.pid}`;
+    writeFileSync(tmp, data, "utf8");
+    renameSync(tmp, file);
+}
+export function upsertInitBlock(file, opts = {}) {
+    const exists = existsSync(file);
+    const original = exists ? readFileSync(file, "utf8") : "";
+    const hadBom = original.charCodeAt(0) === 0xfeff;
+    const body = hadBom ? original.slice(1) : original;
+    const eol = exists ? detectEol(body) : "\n";
+    const block = normalizeBlock(eol);
+    let next = body;
+    let status;
+    if (opts.remove) {
+        if (!exists || !BEGIN_RE.test(body)) {
+            status = "absent";
+        }
+        else {
+            next = removeManagedBlock(body, eol);
+            status = "removed";
+        }
+    }
+    else if (!exists) {
+        next = `${block}${eol}`;
+        status = "created";
+    }
+    else if (BEGIN_RE.test(body)) {
+        const current = body.match(BEGIN_RE)?.[0] ?? "";
+        if (current === block) {
+            status = "ok";
+        }
+        else {
+            next = body.replace(BEGIN_RE, block);
+            status = "updated";
+        }
+    }
+    else {
+        next = insertAfterFirstHeading(body, block, eol);
+        status = "added";
+    }
+    const changed = !["ok", "absent"].includes(status);
+    if (changed && !opts.dryRun) {
+        const out = (hadBom ? "\ufeff" : "") + (next.endsWith(eol) ? next : next + eol);
+        backupOnce(file);
+        atomicWrite(file, out, opts.force === true);
+    }
+    return { file, status, changed };
+}
+function parseArgs(args) {
+    const parsed = {
+        dryRun: false,
+        remove: false,
+        force: false,
+        copilot: false,
+        cursor: false,
+        root: process.cwd(),
+        files: null,
+    };
+    const readValue = (args, i, flag) => {
+        const value = args[i + 1];
+        if (value === undefined || value === "" || value.startsWith("--")) {
+            throw new Error(`${flag} requires a value`);
+        }
+        return value;
+    };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--dry-run")
+            parsed.dryRun = true;
+        else if (a === "--remove" || a === "--uninstall")
+            parsed.remove = true;
+        else if (a === "--force")
+            parsed.force = true;
+        else if (a === "--copilot")
+            parsed.copilot = true;
+        else if (a === "--cursor")
+            parsed.cursor = true;
+        else if (a === "--root") {
+            parsed.root = readValue(args, i, a);
+            i++;
+        }
+        else if (a === "--files") {
+            parsed.files = readValue(args, i, a).split(",").filter(Boolean);
+            i++;
+        }
+        else
+            throw new Error(`unknown init argument: ${a}`);
+    }
+    if (!parsed.root)
+        throw new Error("--root requires a directory");
+    return parsed;
+}
+function isSelfRepo(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return pkg.name === "@heretyc/subagent-mcp";
+    }
+    catch {
+        return false;
+    }
+}
+function targetFiles(root, opts) {
+    const resolveTarget = (f) => {
+        const target = isAbsolute(f) ? resolve(f) : resolve(root, f);
+        const rel = relative(root, target);
+        if (rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))) {
+            return target;
+        }
+        throw new Error(`--files target escapes --root: ${f}`);
+    };
+    if (opts.files)
+        return opts.files.map(resolveTarget);
+    const rel = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+    if (opts.copilot)
+        rel.push(".github/copilot-instructions.md");
+    if (opts.cursor)
+        rel.push(".cursor/rules/subagent-mcp.mdc");
+    return rel.map(resolveTarget);
+}
+export async function runInit(args = process.argv.slice(3)) {
+    let opts;
+    try {
+        opts = parseArgs(args);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+    const root = resolve(opts.root);
+    if (isSelfRepo(root) && !opts.force) {
+        console.error("Refusing to run init inside the subagent-mcp source repo without --force.");
+        console.error("This repo keeps CLAUDE.md/GEMINI.md as thin redirects; use --root for a consumer repo.");
+        return 1;
+    }
+    let files;
+    try {
+        files = targetFiles(root, opts);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+    const issues = [];
+    const results = [];
+    for (const file of files) {
+        try {
+            const r = upsertInitBlock(file, opts);
+            results.push(r);
+            console.log(`${r.status.padEnd(7)} ${file}`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            issues.push(`${file}: ${msg}`);
+            console.error(`failed  ${file}: ${msg}`);
+        }
+    }
+    if (opts.dryRun)
+        console.log("(dry-run: no files written)");
+    if (issues.length > 0) {
+        console.error("\nInit completed with issues:");
+        for (const i of issues)
+            console.error(`- ${i}`);
+        return 1;
+    }
+    return results.length > 0 ? 0 : 1;
+}

package/dist/orchestration/hook-core.js

@@ -11,8 +11,8 @@ import * as reminder from "./reminder.js";
  * turn) READS the marker here and decides what to inject. The hook now emits in
  * BOTH marker states, on a per-prompt counter (reminder.ts): every
  * REMINDER_PERIOD-th prompt injects the LONG mode-specific
- * <ORCHESTRATION-REMINDER-INVARIANT> block, every prompt between injects the
- * one-line pointer at it. Marker ON adds the claim machinery: the claim turn
+ * <ORCHESTRATION-INVARIANT> block, every prompt between injects the
+ * one-line rule carrier. Marker ON adds the claim machinery: the claim turn
  * (fresh enable or carryover re-claim) emits the FULL directive plus the ON
  * reminder block and re-baselines the counter. (Supersedes LOCKED DECISION 2's
  * same-session rel%5 FULL re-emission — owner directive 2026-06-11: steady
@@ -174,10 +174,10 @@ export function classifyClaim(owner_session, baseline_turn, current) {
 }
 /**
  * Per-prompt reminder cadence emission: the LONG block (longFile) on every
- * REMINDER_PERIOD-th counted prompt, the one-line pointer between. When the
+ * REMINDER_PERIOD-th counted prompt, the one-line rule carrier between. When the
  * counter could NOT persist, emit the LONG block — fail VISIBLE: a host whose
- * temp dir cannot hold the state file would otherwise inject the pointer on
- * every prompt at a block that never arrives.
+ * temp dir cannot hold the state file would otherwise inject only the compact
+ * rule carrier on every prompt and never refresh the LONG block.
  */
 function cadenceEmit(env, adapter, longFile, count, persisted) {
     return !persisted || count % REMINDER_PERIOD === 0
@@ -218,14 +218,14 @@ export function claimAndEmit(cwd, current, turn, m, kind, env, adapter) {
  *     does not advance).
  *  2. marker not active for cwd -> OFF cadence: advance the session's counter
  *     (per-owner; a new session starts its own), LONG OFF-variant reminder when
- *     count % REMINDER_PERIOD === 0, else the one-line pointer.
+ *     count % REMINDER_PERIOD === 0, else the one-line rule carrier.
  *  3. marker active: classify the claim from marker state.
  *  4. FRESH / CARRYOVER -> claimAndEmit (FULL + ON reminder; CARRYOVER notice
  *     prepended once per marker; counter re-baselined). The transcript turn is
  *     read ONLY here — claim turns are the only consumer of the baseline, and
  *     the tail read is too expensive for the per-prompt steady state.
  *  5. SAME-SESSION -> ON cadence: LONG ON-variant reminder when
- *     count % REMINDER_PERIOD === 0, else the one-line pointer.
+ *     count % REMINDER_PERIOD === 0, else the one-line rule carrier.
  */
 export function runHook(payload, env, adapter) {
     try {

package/dist/orchestration/liveness.js

@@ -0,0 +1,32 @@
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateDir } from "./marker.js";
+export const LIVENESS_TTL_MS = 120_000;
+export const LIVENESS_INTERVAL_MS = 30_000;
+export function alivePath() {
+    return join(stateDir, "alive.flag");
+}
+export function touchAlive(now = Date.now()) {
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(alivePath(), `${now}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Hooks fail open when liveness cannot be observed.
+    }
+}
+export function serverAlive(now = Date.now()) {
+    try {
+        const s = statSync(alivePath());
+        return now - s.mtimeMs <= LIVENESS_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+}
+export function startLivenessHeartbeat() {
+    touchAlive();
+    const t = setInterval(() => touchAlive(), LIVENESS_INTERVAL_MS);
+    t.unref();
+    return t;
+}

package/dist/orchestration/pretool.js

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cwdHash, stateDir } from "./marker.js";
+import { serverAlive } from "./liveness.js";
+import { sessionKey } from "./hook-core.js";
+export const INLINE_TOOL_LIMIT = 5;
+const NATIVE_SUBAGENT_TOOLS = new Set(["Task", "Agent", "Explore"]);
+const QUESTION_TOOLS = new Set(["AskUserQuestion", "ExitPlanMode"]);
+const SUBAGENT_MCP_TOOL_RE = /(^|__)subagent[-_]?mcp(__|$).*(launch_agent|poll_agent|wait|list_agents|send_message|kill_agent)$/i;
+function hash(s) {
+    return createHash("sha256").update(s, "utf8").digest("hex").slice(0, 16);
+}
+function owner(payload) {
+    return sessionKey(payload) ?? "null";
+}
+function countPath(payload) {
+    const cwd = payload.cwd || process.cwd();
+    return join(stateDir, `pretool-${cwdHash(cwd)}-${hash(owner(payload))}.json`);
+}
+function readCount(payload) {
+    try {
+        const parsed = JSON.parse(readFileSync(countPath(payload), "utf8"));
+        return typeof parsed.count === "number" && parsed.count >= 0 ? parsed.count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function writeCount(payload, count) {
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(countPath(payload), JSON.stringify({ owner: owner(payload), count, updated_at: Date.now() }), { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Fail open: counter persistence is advisory enforcement, not host safety.
+    }
+}
+export function resetToolCount(payload) {
+    try {
+        if (existsSync(countPath(payload)))
+            unlinkSync(countPath(payload));
+    }
+    catch {
+        // Fail open.
+    }
+}
+function decision(permissionDecision, permissionDecisionReason, additionalContext) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision,
+            permissionDecisionReason,
+            ...(additionalContext ? { additionalContext } : {}),
+        },
+    };
+}
+function isSubagentMcpTool(tool) {
+    return (SUBAGENT_MCP_TOOL_RE.test(tool) ||
+        [
+            "launch_agent",
+            "poll_agent",
+            "wait",
+            "list_agents",
+            "send_message",
+            "kill_agent",
+        ].includes(tool));
+}
+function exemptFromCounter(tool) {
+    return isSubagentMcpTool(tool) || QUESTION_TOOLS.has(tool);
+}
+export function runClaudePreTool(payload, env, now = Date.now()) {
+    try {
+        if (env.SUBAGENT_MCP_SUBAGENT === "1")
+            return null;
+        if (!serverAlive(now))
+            return null;
+        const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
+        if (!tool)
+            return null;
+        if (NATIVE_SUBAGENT_TOOLS.has(tool)) {
+            return decision("deny", "subagent-mcp is alive; harness-native Task/Agent/Explore is not the sanctioned sub-agent channel. Use the subagent-mcp launch_agent MCP tool with the parent-process sentinel as prompt line 1.");
+        }
+        if (exemptFromCounter(tool))
+            return null;
+        const next = readCount(payload) + 1;
+        writeCount(payload, next);
+        if (next <= INLINE_TOOL_LIMIT)
+            return null;
+        return decision("ask", `5-CALL RULE: this is tool call ${next} for the current user request. If work remains, delegate through subagent-mcp launch_agent; allow only for main-session-only capability or tight verification.`, "5-CALL RULE reached. Route remaining non-main-session work through subagent-mcp launch_agent; inline only for main-session-only capability or tight verification.");
+    }
+    catch {
+        return null;
+    }
+}